开发者 API
一个接口完成文档识别
使用带 OCR scope 的服务端 Developer API Key 鉴权，一次提交一个文件、公开图片 URL 或 Base64 内容，并获得标准化 OCR 输出。识别成功后扣除 Processing Credits，有效 key 的调用都会写入日志，方便统计用量。
HTTP 接口
POST https://your-domain.com/api/v1/ocr
Authorization: Bearer YOUR_API_KEY
OpenAPI: GET /api/v1/openapicurl 文件上传
curl -X POST https://your-domain.com/api/v1/ocr \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: invoice-001" \
-F "[email protected]" \
-F "mode=formatted"JavaScript 图片 URL
// 请在你的后端运行，不要放到浏览器 JavaScript 中。
const res = await fetch('https://your-domain.com/api/v1/ocr', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.DEVELOPER_API_KEY}`,
'Idempotency-Key': 'scan-001',
'Content-Type': 'application/json'
},
body: JSON.stringify({
image_url: 'https://example.com/scan.png',
mode: 'simple'
})
});
const data = await res.json();Python Base64
import base64
import requests
with open('receipt.jpg', 'rb') as f:
encoded = base64.b64encode(f.read()).decode('utf-8')
res = requests.post(
'https://your-domain.com/api/v1/ocr',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={
'base64': encoded,
'mime_type': 'image/jpeg',
'file_name': 'receipt.jpg',
'mode': 'formatted'
},
timeout=120,
)
print(res.json())请求字段
file
Multipart 图片或 PDF 文件，支持格式与网页 OCR 工作区一致。
image_url
远程图片或 PDF 的公开 HTTP/HTTPS 地址。私网、localhost、link-local 和 metadata 地址会在识别前被拒绝。
base64
Base64 文件内容。非 data URL 时建议同时传入 mime_type 和 file_name。
mode
simple 返回纯文本；formatted 返回 Markdown、表格、公式和版面块。
Idempotency-Key
可选请求头，用于安全重试。同一个 key 和同一个输入在 24 小时内可重放成功结果，不会重复扣费。
响应约定
200 success
返回 success、request_id、elapsed_ms、markdown、text、pages 和 usage。
401 unauthorized
API Key 缺失、无效或已禁用。
402 credits_insufficient
Key 所属用户 Processing Credits 不足，无法覆盖预计页数和识别模式。
409 idempotency_conflict
同一个 Idempotency-Key 已经被不同 OCR 输入使用。
422 empty_result
输入已处理，但没有识别到可读文字。
429 limit_exceeded 或 rate_limited
触发每日 API 限制、页数限制或最小请求间隔。
为产品集成准备
API 使用与网页产品一致的 OCR 规范化、Processing Credit 规则和限制体系。
Developer API Key 鉴权
用户可以创建带 OCR scope 的 Developer API Key。完整密钥只显示一次，应保存在服务端。
Processing Credit 计量
Simple 和 Formatted 按页消耗 Processing Credits，识别成功后才扣除。
调用日志
有效 key 的请求会记录 request_id、状态、耗时、Processing Credits、来源类型、IP 和 User-Agent。
数据处理边界
API 日志保存计量元数据，用于监控和滥用检测。OCR 输出返回给调用方，识别失败不扣积分。
OCR API 常见问题
开发者关心的鉴权、扣费和响应格式。