API Reference
API 概述
所有开发者 API 端点的通用概念——错误码、限流、计费、幂等性和输入格式。
基础 URL
https://image-to-text.org/api/v1所有端点均为同步请求——结果在同一个 HTTP 响应中返回。
认证
每个请求必须包含 API 密钥。设置方法请参见快速开始。
Authorization: Bearer YOUR_API_KEY或：
x-api-key: YOUR_API_KEY缺少有效密钥的请求返回 401 Unauthorized。密钥必须具有对应端点的正确权限范围（例如 OCR 端点需要 ocr 权限，图片处理端点需要 image 权限）。
请求 ID
每个响应包含一个 request_id——该请求的唯一标识符。联系客服时请提供此 ID。它也会出现在您的 API 请求日志中，用于计费和调试。
错误码
所有错误遵循统一格式：
| 状态码 | 错误码 | 可重试 | 含义 |
|---|---|---|---|
| 401 | unauthorized | 否 | 缺少、无效或已禁用的 API 密钥 |
| 402 | credits_insufficient | 否 | 处理积分不足 |
| 400 | file_error | 否 | 无输入、多个输入或无效的输入格式 |
| 409 | idempotency_conflict | 否 | 使用不同输入重用了幂等键 |
| 413 | limit_exceeded | 否 | 文件过大或页数过多 |
| 415 | invalid_input | 否 | 不支持的图片格式 |
| 422 | empty_result | 否 | 文件中未找到可读文字 |
| 429 | rate_limited | 是 | 请求过于频繁——等待指定秒数后重试 |
| 429 | limit_exceeded | 否 | 达到每日请求上限 |
| 500 | config_error | 否 | 服务未配置 |
| 502 | network_error | 是 | 无法连接到处理服务提供商 |
| 504 | upstream_timeout | 是 | 服务提供商超时——可重试 |
可重试的错误可以安全重试。建议使用指数退避策略（从 1 秒开始，每次翻倍，最多重试 3 次）。
限流
每个 API 密钥的限流规则分别适用于 OCR 和图片处理权限：
- 请求之间的最小间隔（可配置，默认约 5 秒）
- 每日请求上限——免费用户和付费用户有不同的限额
触发限流时，响应会包含 Retry-After 请求头，指示需要等待的秒数。
计费
请求按处理积分计费：
| 端点 | 计费依据 |
|---|---|
| OCR（简单模式） | 每页 1 积分 |
| OCR（格式化模式） | 每页 10 积分 |
| 图片转换 | 基于像素工作量 |
| 图片压缩 | 基于像素工作量 |
仅在处理成功后扣除积分。失败的请求不收费。
幂等性
对于计费端点，可提供 Idempotency-Key 请求头来防止重试时重复计费：
Idempotency-Key: <字母数字字符串，最长 191 个字符>- 幂等键与您的 API 密钥绑定，有效期为 24 小时
- 相同键 + 相同输入 → 返回缓存结果，不再扣费
- 相同键 + 不同输入 →
409 idempotency_conflict错误 - 推荐格式：
{操作}-{时间戳}-{唯一后缀}
输入格式
OCR
| 格式 | 文件扩展名 | 备注 |
|---|---|---|
| JPEG | .jpg、.jpeg | |
| PNG | .png | |
| GIF | .gif | |
| WebP | .webp | |
| BMP | .bmp | |
| TIFF | .tif、.tiff | 仅单张图片 |
.pdf | 最大 20MB |
图片处理
输入格式：JPEG、PNG、WebP、AVIF、GIF、TIFF（静态）
输出格式：JPEG、PNG、WebP、AVIF
多种输入方式
每个端点支持三种方式提供源文件：
| 方式 | Content-Type | 字段 |
|---|---|---|
| 文件上传 | multipart/form-data | file |
| 公开 URL | multipart/form-data 或 application/json | image_url |
| Base64 | multipart/form-data 或 application/json | base64 + mime_type |
远程 URL 必须是公开可访问的地址。私有地址、本地地址、链路本地地址和云元数据地址会被拦截。