图片转文字 | FreeAIOCR

POST /api/v1/image-to-text

发送请求

通过 POST 在 multipart image 字段上传且仅上传一张图片，将示例中的 YOUR_API_KEY 和 document.png 替换为真实值。让 cURL 设置 multipart 边界。仅支持可选的 format 查询参数，不接受额外表单字段或模型设置。使用前请阅读Bearer 认证与密钥安全说明。

curl --silent --show-error --include --max-time 150 \
  'https://freeaiocr.com/api/v1/image-to-text' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: example-request-0001' \
  -F 'image=@document.png'

下方 JSON 是示例，识别结果与 token 用量取决于图片；重试时请遵循幂等规则。

成功响应（用量算例）

{
  "request_id": "b2c8ec98-2a36-4f87-99d2-3d7839b92518",
  "text": "# Document title\n\nRecognized paragraph.\n\n| Item | Count |\n| --- | --- |\n| Books | 12 |",
  "usage": {
    "input_tokens": 2000,
    "output_tokens": 4000
  },
  "billing": {
    "currency": "USD",
    "price_version": "2026-10-26-v1",
    "base_usd": "0.002000000",
    "input_overage_usd": "0.000000000",
    "output_overage_usd": "0.002400000",
    "total_usd": "0.004400000"
  }
}

输出格式

仅接受一个可选查询参数：format=json|text|docx。未知参数、重复 format 或不支持的格式会在识别前返回 400。

json（默认）：JSON 的 text 包含 Markdown，可含 HTML 表格和 LaTeX；usage 和 billing 保持原有结构
text：相同 JSON 外壳，仅将 text 转为纯文本
docx：Word 二进制附件 result.docx，Content-Type 为 application/vnd.openxmlformats-officedocument.wordprocessingml.document，并带有 Content-Disposition: attachment

纯文本示例：

curl --silent --show-error --include --max-time 150 \
  'https://freeaiocr.com/api/v1/image-to-text?format=text' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: example-request-0001' \
  -F 'image=@document.png'

Word 示例（仅在 cURL 成功且响应 Content-Type 为 Word 时使用下载文件）：

curl --silent --show-error --fail --max-time 150 \
  'https://freeaiocr.com/api/v1/image-to-text?format=docx' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: example-request-0001' \
  -F 'image=@document.png' \
  --dump-header - --output result.docx

转换响应保留 X-Request-Id、Cache-Control: no-store 及适用的 Idempotency-Replayed；X-OCR-Charged-USD 与 X-OCR-Price-Version 对应原始识别的费用和价格版本。

在 24 小时内，保持同一账户、原始图片字节、MIME 和 Idempotency-Key 切换格式，不新增识别扣费。旧纯文本结果也可转换，但无法恢复旧结果已经丢失的结构。到期后再提交可能创建新的计费识别。

export_failed（503）表示识别已成功并扣费，但转换失败，JSON 错误中有 recognition_succeeded: true。请在结果有效期内用原图片和原键重试，或改用 format=json；转换失败不会退款或重新识别。它与已确认的识别失败不同，不要将下载失败当作免费的新操作。

Word 保留可编辑文字和表格，不还原原图排版；公式保留为 LaTeX 文本。使用前请核对识别内容及表格结构。

不同操作或接口必须使用新的 Idempotency-Key；图片转文字和图片转表格复用编号会返回 409 idempotency_conflict。同一操作切换格式则保留原编号和图片。通用细则请查阅幂等与重试及价格与计费。