公开 API

API 文档

将 SotaOCR 集成到你的 AI 代理和 LLM 流水线中。API 采用异步模式：先上传文档，再轮询任务状态，最后获取结果，或者在需要时获取与 OCR bbox 相同坐标空间的页面预览图像。

基础 URL

所有公开 OCR 端点都从这个主机提供。

https://sotaocr.com

鉴权

所有 API 请求都需要 Bearer Token。你可以在控制台中创建 API Key。

请求头

Authorization: Bearer YOUR_API_KEY

可用路由

OCR 服务提供这些 API 路由：/v1/balance、/v1/extract、/v1/jobs/{job_id}、/v1/jobs/{job_id}/result、/v1/jobs/{job_id}/result.html、/v1/jobs/{job_id}/result.docx，以及 /v1/jobs/{job_id}/pages/{page_number}/preview。发送 model_profile 前，请先通过 GET /api/v1/info 读取 model_profiles。HTML 和 DOCX 重建导出目前仅支持 FAST 模型任务。

OCR 预处理

在主 OCR 之前，服务会自动检测页面方向、旋转页面，并仅在需要时执行 document unwarping。检测到的角度会返回在 doc_preprocessor_res.angle 中，而 preview 端点返回的就是与 OCR bbox 使用同一坐标空间的准确页面图像。

轮询与结果就绪

请将查询频率控制在每秒最多 1 次。在 OCR 完成之前，GET /v1/jobs/{job_id}/result 会返回带有 result_not_ready 的 202 Accepted。

Pro OCR

启用 Pro 模型时，请在 /v1/extract 中发送 model_profile=pro，以使用更高质量的 OCR。Pro OCR 每处理 1 个文档页面会消耗 2 scan pages。

cURL · Pro 请求

curl -X POST https://sotaocr.com/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F 'page_ranges=[{"start":1,"end":5}]' \
  -F "model_profile=pro"

JSON · 响应

{
  "id": "job_123456789",
  "account_id": "acct_123456789",
  "status": "pending",
  "page_count": 5,
  "pages_completed": 0,
  "model_profile": "pro",
  "upstream_job_id": "up_job_987654321",
  "created_at": "2026-03-24T12:00:00Z",
  "updated_at": "2026-03-24T12:00:00Z"
}

GET

检查页面余额

/v1/balance 返回已认证账号当前的 scan page 余额。使用 remaining_pages 或 total_affordable_pages 判断还可以处理多少页。

cURL · 请求

curl -X GET https://sotaocr.com/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON · 响应

{
  "entity_code": "scan_page",
  "remaining_pages": 63,
  "total_affordable_pages": 63,
  "monthly_pages": {"total": 40, "allocated": 5, "remaining": 35},
  "lifetime_pages": {"total": 20, "allocated": 2, "remaining": 18},
  "tokens": {"total": 120, "allocated": 20, "remaining": 100, "affordable_pages": 10},
  "token_price": 10
}

POST

1. 上传文档

/v1/extract 上传 PDF 或图片进行 OCR。成功时返回 202 Accepted，以及包含 account_id、upstream_job_id、created_at 和 updated_at 的任务元数据。

file: 文档文件 (PDF, PNG, JPG)。
page_ranges: （可选）页面范围数组的 JSON 字符串。例如：'[{"start":1,"end":3}]'
model_profile: 可选 OCR 模型配置。省略该字段将使用服务默认值；如需指定，请发送 GET /api/v1/info 的 model_profiles 中返回的值。

cURL · 请求

curl -X POST https://sotaocr.com/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F 'page_ranges=[{"start":1,"end":5}]'

JSON · 响应

{
  "id": "job_123456789",
  "account_id": "acct_123456789",
  "status": "pending",
  "page_count": 5,
  "pages_completed": 0,
  "model_profile": "fast",
  "upstream_job_id": "up_job_987654321",
  "created_at": "2026-03-24T12:00:00Z",
  "updated_at": "2026-03-24T12:00:00Z"
}

GET

2. 查询状态

/v1/jobs/{job_id} 返回 200 OK 和当前处理状态，同时包含 account_id、upstream_job_id、page_count、pages_completed、created_at 和 updated_at。

cURL · 请求

curl -X GET https://sotaocr.com/v1/jobs/job_123456789 \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON · 响应

{
  "id": "job_123456789",
  "account_id": "acct_123456789",
  "status": "completed",
  "page_count": 5,
  "pages_completed": 5,
  "upstream_job_id": "up_job_987654321",
  "created_at": "2026-03-24T12:00:00Z",
  "updated_at": "2026-03-24T12:00:08Z"
}

GET

3. 获取结果

/v1/jobs/{job_id}/result?format=markdown 任务 completed 后返回 200 OK 和提取内容。对于 format=json，每页可能包含带 angle 的 doc_preprocessor_res，以及描述 bbox 坐标空间的 page_preview 元数据。format=html 会在 JSON envelope 内返回重建 HTML，目前仅支持 FAST；如需带嵌入图片的独立 HTML 文件，请使用 /result.html。完成前接口返回带 result_not_ready 的 202 Accepted。

format: （可选）响应格式：json、markdown、text 或 html。默认 json。html 目前仅支持 FAST。

cURL · 请求

curl -X GET "https://sotaocr.com/v1/jobs/job_123456789/result?format=markdown" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON · 响应

{
  "job_id": "job_123456789",
  "format": "json",
  "page_count": 1,
  "content": "{\"job_id\":\"job_123456789\",\"page_count\":1,\"pages\":[{\"page_number\":1,\"status\":\"completed\",\"text\":\"Ivan Matveev\",\"doc_preprocessor_res\":{\"angle\":0,\"model_settings\":{\"use_doc_orientation_classify\":true,\"use_doc_unwarping\":false}},\"page_preview\":{\"coordinate_space\":\"doc_preprocessed\",\"content_type\":\"image/png\",\"width\":1192,\"height\":1684},\"raw_result\":{}}]}"
}

GET

4. 获取独立 HTML

/v1/jobs/{job_id}/result.html 返回 FAST 和 PRO 任务的 text/html 重建结果，并嵌入 data-URI 图片。

cURL · 请求

curl -X GET "https://sotaocr.com/v1/jobs/job_123456789/result.html" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output result.html

JSON · 响应

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Disposition: inline; filename="job_123456789.html"

(带 data-URI 嵌入图片的独立 HTML)

GET

5. 获取 DOCX 重建

/v1/jobs/{job_id}/result.docx 返回 FAST 和 PRO 任务的二进制 .docx 视觉重建文件，包含页面图片和可搜索 OCR 文本。

cURL · 请求

curl -X GET "https://sotaocr.com/v1/jobs/job_123456789/result.docx" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output result.docx

JSON · 响应

HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="job_123456789.docx"

(二进制 DOCX bytes)

GET

6. 获取用于 bbox 覆盖层的页面 preview

/v1/jobs/{job_id}/pages/{page_number}/preview 返回经过自动旋转和可选 unwarp 之后的 PNG 页面图像。这就是应该放在 OCR bbox 背后的那张图。

cURL · 请求

curl -X GET https://sotaocr.com/v1/jobs/job_123456789/pages/1/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output page_0001_preview.png

JSON · 响应

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: inline; filename="page_0001_preview.png"

(与 OCR bbox 使用同一坐标空间的 PNG 二进制内容)

API 错误

大多数错误响应使用 {"error":{"code":"...","message":"..."}}。insufficient_balance 还会包含 entity_code、requested_units 和 available_units。

400 错误请求: 无效的 multipart、缺少 file、无效的 page_ranges 或无效 PDF。错误码：bad_request。
401 未授权: 缺少 Bearer Token 或 Token 无效。错误码：unauthorized。
403 禁止访问: 需要 API 访问权限，或余额不足。错误码：api_access_required 或 insufficient_balance。
404 未找到: 未知的 job_id，或尝试访问其他账号的任务。错误码：job_not_found。
415 不支持的媒体类型: 上传的文件类型不受支持。错误码：unsupported_media。
502 Upstream 不可用: OCR upstream 不可用，或任务同步失败。错误码：upstream_unavailable。

准备开始集成？

在控制台创建 API Key，并获得免费的测试页数。

打开控制台获取 API 访问权限下载技能