captchaocr.cnCaptchaOCR验证码识别 API 参考
CaptchaOCR 通过 HTTP POST 接收验证码图片文件或 Base64，返回 JSON 格式的识别文本、置信度与验收状态。单张接口为 /api/v1/recognize，批量接口为 /api/v1/recognize/batch。
鉴权
识别接口需通过 X-API-Key 或 Authorization: Bearer 请求头提供 API 密钥。 密钥缺失或无效时，接口会返回鉴权错误；请检查密钥是否完整、有效，并仅在服务端使用。
上传图片
POST /api/v1/recognize 接受验证码图片文件，也接受 Base64。文件使用 multipart/form-data 的 file 字段。Base64 放在 JSON 的 image 或 image_base64 字段，也可以用同名表单字段提交；内容可以是标准 Base64、URL-safe Base64，或 data:image/...;base64,...。两种方式只能提交一种。
批量接口 POST /api/v1/recognize/batch 同样兼容：重复提交 files 文件，或提交 images / images_base64 字符串数组。单条 Base64 无法解析时，只影响对应条目。
查询参数
单张和批量接口均支持以下参数。不传字符集、长度或阈值时采用服务端配置；建议显式传入适合图片的设置。
| 参数 | 取值与作用 |
|---|---|
charset | auto、digits、alnum、alnum_lower、alnum_upper、alnum_caseless；custom 需服务端预先配置。 |
expected_length | 0–64 的整数；0 关闭长度校验，其他值要求识别文本符合指定长度。 |
min_confidence | 0–1 的数值；低于阈值时验收不通过。置信度是模型评分，不是实测准确率。 |
strict | 默认 false。设为 true 后，单张识别验收不通过返回 HTTP 422。 |
纯数字图选择 digits；含大小写字母时使用 auto 或 alnum。alnum_caseless 会将字母统一为小写，适合不区分大小写的业务。
返回字段与验收状态
| 字段 | 含义 |
|---|---|
text | 按字符集过滤后的识别文本，可能为空。 |
confidence | 0–1 的置信度，按各分段长度加权；不能当作识别准确率。 |
accepted | 结果是否通过当前验收条件，不保证每个字符正确。 |
rejection_reason | 未通过原因：empty、low_confidence 或 length_mismatch；通过时为 null。 |
request_id | 请求标识，与响应头 X-Request-ID 一致，用于排查调用问题。 |
普通模式下，HTTP 200 表示识别请求已处理；accepted 表示结果是否满足配置的置信度与期望长度条件，不保证识别正确。严格模式 strict=true：验收未通过时返回 422（low_confidence / length_mismatch）。
批量是部分成功
批量响应会逐项返回识别结果或失败信息，单张图片失败不会阻止其他图片处理。未知字符集会使整个请求返回 400；识别引擎未就绪时，整个请求返回 503。
常见 HTTP 错误如何处理
| 状态码 | 原因与处理 |
|---|---|
| 400 | 参数、图片解码或数量不合法；先修正输入。 |
| 401 | 缺少或无效的密钥；核对完整密钥与请求头。 |
| 402 | insufficient_credits：积分不足，补充积分后再调用。 |
| 403 | 邮箱未验证或账号无权限；检查错误码及账号状态。 |
| 413 / 415 | 上传内容过大或格式不支持；检查文件大小和实际图片格式。 |
| 422 | 严格模式下验收未通过；核对图片与识别条件。 |
| 429 | 频率超限；按 Retry-After 等待，并减少并发。 |
| 503 | 引擎未就绪或不可用；稍后重试或使用业务降级流程。 |
请求频率与积分
每分钟配额按图片张数计数；批量提交 16 张图片会占用 16 个请求额度。超限时返回 429，请参考 Retry-After 与 X-RateLimit-*。
注册用户验证邮箱后可领取注册积分；已验证账号登录后，每个北京时间自然日可自动领取一次登录积分。具体额度和换算以定价页为准。 每次完成识别消耗 1 积分，包括未通过验收的结果；余额不足时返回 402 insufficient_credits。 未验证邮箱时返回 403 email_unverified。通过环境变量配置的服务密钥不扣账户积分。
控制台试识别
控制台通过 POST /api/v1/account/try-recognize 和登录 Cookie 提交图片，无需在浏览器中保存或填写 API 密钥。