OCR API 参考

OCR 端点的完整参考——请求参数、响应结构、代码示例和支持的选项。

端点

POST /api/v1/ocr

所需权限： ocr

请求

请求头

请求头	必需	说明
`Authorization: Bearer <key>`	是*	带有 `ocr` 权限的 API 密钥
`x-api-key: <key>`	是*	Bearer token 的替代方式
`Idempotency-Key`	否	安全重试键（最长 191 字符，允许字母数字和 `._:-`）
`Content-Type`	是	`multipart/form-data` 或 `application/json`

*必须提供其中一个认证请求头。

输入来源（选择一种）

字段	类型	来源
`file`	二进制	通过 multipart 上传文件
`image_url`	字符串 (URI)	公开的 HTTP/HTTPS URL
`base64`	字符串	Base64 编码的文件内容

使用 base64 时，还需提供 mime_type（如 image/png、application/pdf）。

模式

字段	类型	默认值	可选值
`mode`	字符串	`formatted`	`simple`、`formatted`

simple — 纯文本输出（成本较低，每页 1 积分）
formatted — 保留标题、表格、列表、代码块的 Markdown 格式（每页 10 积分）

响应

成功 (200)

{
  "success": true,
  "request_id": "req_abc123...",
  "elapsed_ms": 2340,
  "data": {
    "markdown": "# 发票\n\n| 项目 | 数量 | 价格 |\n|------|------|------|\n...",
    "text": "发票\n项目 数量 价格\n...",
    "pages": [
      {
        "pageNumber": 1,
        "markdown": "# 发票\n\n...",
        "text": "发票\n...",
        "blocks": [
          {
            "type": "heading",
            "markdown": "# 发票",
            "bbox": [72, 100, 540, 130],
            "confidence": 0.98
          }
        ]
      }
    ],
    "usage": {
      "credits": 10,
      "pages": 1,
      "mode": "formatted"
    }
  }
}

响应字段

字段	类型	说明
`success`	布尔	成功时始终为 `true`
`request_id`	字符串	此请求的唯一标识符
`elapsed_ms`	整数	处理耗时（毫秒）
`data.markdown`	字符串	完整文档 Markdown（所有页面拼接）
`data.text`	字符串	文档的纯文本版本
`data.pages`	数组	每页结果
`data.usage`	对象	计费摘要

Page 对象

字段	类型	说明
`pageNumber`	整数	基于 1 的页码
`markdown`	字符串	页面 Markdown 内容
`text`	字符串	页面纯文本
`blocks`	数组	识别的文本块

Block 对象

字段	类型	说明
`type`	字符串	`heading`、`paragraph`、`list`、`table`、`code`
`markdown`	字符串	Markdown 格式的块内容
`bbox`	[数字]	`[x1, y1, x2, y2]` 边界框坐标
`confidence`	数字	识别置信度（0–1）

限制

限制项	值
最大文件大小	20 MB
每请求最大页数	可配置（默认约 50）
支持的图片格式	JPEG、PNG、GIF、WebP、BMP、TIFF
支持的文档格式	PDF

代码示例

Python

import requests

response = requests.post(
    "https://image-to-text.org/api/v1/ocr",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
    files={"file": open("document.pdf", "rb")},
    data={"mode": "formatted"},
)

data = response.json()
if data["success"]:
    print(data["data"]["markdown"])

Node.js

const form = new FormData();
form.append("file", fileInput);
form.append("mode", "formatted");

const response = await fetch("https://image-to-text.org/api/v1/ocr", {
  method: "POST",
  headers: { "Authorization": "Bearer YOUR_API_KEY" },
  body: form,
});

const data = await response.json();
console.log(data.data.markdown);

OCR API 参考

On this page