API 接入文档

从认证到文件交付：查询请求路径、参数、响应结构与错误处理。

申请与认证

发送邮件说明项目、已验证 iSomor 账号邮箱、文档场景和预计用量，我们会尽快回复审核结果。审核通过后，一次提供调用凭证、基础地址和免费额度，无需再次创建 Key。每次请求携带 Authorization: Bearer <API_KEY>。凭证只放服务端环境变量，不放 Cookie、URL、前端或 AI 提示词；撤销和轮换请联系支持邮箱，不发送完整 Key。

下方命令设置正式 ISOMOR_API_BASE_URL（含 /api/isomor/v1 前缀，无末尾斜杠）。通过服务端的秘密管理工具设置 ISOMOR_API_KEY，不将真实凭证写进命令历史或代码。下方 curl 示例读取这两个环境变量，未设置时会提示补充。JSON 请求使用 Content-Type: application/json；上传使用 multipart/form-data，由 HTTP 客户端生成 boundary。响应格式为 JSON，HTTP 状态码用于区分成功与错误。

export ISOMOR_API_BASE_URL="https://tryisomor.com/api/isomor/v1"

邮件申请 API ↗

[email protected]

调用顺序

查询能力 → 上传 PDF → 将返回的 id 用作 file_id → 创建任务并保存 job_id → 查询状态 → 获取下载链接。创建前可查询额度，但查询余额不等于预留额度。请求失败时按下方幂等和重试规则处理，避免重复创建任务。

GET/capabilities查询能力与限制 ↗POST/files上传 PDF ↗POST/translations创建翻译任务 ↗GET/translations/{job_id}查询任务状态 ↗GET/translations/{job_id}/results获取结果文件 ↗GET/quota查询 API 额度 ↗

下载与快速开始

可将 OpenAPI 文件导入支持该格式的开发工具，其中 baseUrl 已默认配置正式 API 地址。Python 示例适用于 Python 3.10 及以上，无需安装第三方依赖；运行前按上方说明配置两个环境变量。

以下命令只翻译第 1 页，最多使用 1 积分，获取译文和双语 PDF。--submit 会上传文件并提交翻译；不带 --submit 或 --resume 时不会发请求。若调整页段，请同时确认 --max-credits 上限；预计超出上限时只完成上传，不创建翻译。

python3 translate_pdf.py \
  --file ./sample.pdf --target zh --pages 1 \
  --max-credits 1 --output ./translation-001 --submit

中断后继续同一任务

保留输出目录，使用同一项目的凭证恢复。示例保存原请求和幂等键，已知任务只查询、不重新创建；受理结果不明且超过安全重试窗口时停止。已保存且摘要一致的文件会跳过，过期下载链接会重新获取。默认每次最多等待 600 秒，可用 --timeout 调整至最多 3600 秒。

python3 translate_pdf.py --output ./translation-001 --resume

输出目录包含私有 PDF 和 state.json 恢复信息，不要提交到 Git 或公开分享。凭证不会写入状态文件，也不会发送到文件下载地址。示例不会覆盖已有文件；没有成功返回文件 ID 的上传不自动重试。

GET/capabilities

查询能力与限制

接入前读取支持的语言、输出格式及该凭证的限制。具体限制以接口返回值为准。

所需权限: capabilities:read

请求参数

无路径、查询或请求体参数；仍需 Bearer 认证。

请求示例

: "${ISOMOR_API_BASE_URL:?Set ISOMOR_API_BASE_URL}" &&
: "${ISOMOR_API_KEY:?Set ISOMOR_API_KEY}" &&
curl --request GET "${ISOMOR_API_BASE_URL}/capabilities" \
  --header "Authorization: Bearer ${ISOMOR_API_KEY}"

响应字段

source_languages / target_languagesstring[]: 可用语言代码；auto 仅用于源语言。
input_mime_types / output_formatsstring[]: 首期仅文字 PDF；输出 translated 或 bilingual。
credits_per_pageinteger: 每页文字 PDF 消耗的积分数。
limitsobject: max_file_bytes、max_pages、max_concurrent_jobs、requests_per_minute 均为正整数；max_storage_bytes 为源文件与选页副本合计的输入存储额度。以实际响应为准。

200 · 响应示例

{
  "source_languages": [
    "auto",
    "en",
    "zh"
  ],
  "target_languages": [
    "en",
    "zh"
  ],
  "input_mime_types": [
    "application/pdf"
  ],
  "credits_per_page": 1,
  "output_formats": [
    "translated",
    "bilingual"
  ],
  "limits": {
    "max_file_bytes": 10485760,
    "max_pages": 20,
    "max_concurrent_jobs": 1,
    "requests_per_minute": 30,
    "max_storage_bytes": 104857600
  }
}

POST/files

上传 PDF

上传单个 PDF，校验通过后返回文件 ID（响应字段 id），创建任务时传给 file_id。此操作不启动翻译；每次上传会创建独立文件记录。

所需权限: files:write · multipart/form-data

请求参数

filebinary · required: 本地 PDF 文件的二进制内容，不接受本地路径字符串或远程 URL；需可提取文字且未加密。

请求示例

: "${ISOMOR_API_BASE_URL:?Set ISOMOR_API_BASE_URL}" &&
: "${ISOMOR_API_KEY:?Set ISOMOR_API_KEY}" &&
curl --request POST "${ISOMOR_API_BASE_URL}/files" \
  --header "Authorization: Bearer ${ISOMOR_API_KEY}" \
  --form 'file=@./sample.pdf;type=application/pdf'

响应字段

idstring: 不透明的文件 ID，归属于该接入身份；创建任务时传给 file_id。
filename / media_typestring: 规范化后的安全文件名及 application/pdf。
page_countinteger: 校验后的总页数，大于 0。

201 · 响应示例

{
  "id": "file_example",
  "filename": "sample.pdf",
  "media_type": "application/pdf",
  "page_count": 3
}

POST/translations

创建翻译任务

校验文件、语言、页段与额度后异步入队。202 只表示任务已接收，不表示翻译完成。必须携带 Idempotency-Key，重试沿用同一值。

所需权限: translations:write · application/json

请求参数

file_idstring · required: 本凭证所属接入身份上传的文件 ID。
target_languagestring · required: 目标语言代码，取自 /capabilities；不能使用 auto。
source_languagestring · optional: 源语言代码，默认 auto 自动识别。
pagesstring · optional: 省略表示全文；例如 1-3,5，页码从 1 开始、含端点、不能超出总页数，重复页只计一次；输出仅含选定页，按原文顺序排列。
output_formatsstring[] · optional: 非空、去重的格式列表：translated / bilingual；默认两种都输出。

请求示例

: "${ISOMOR_API_BASE_URL:?Set ISOMOR_API_BASE_URL}" &&
: "${ISOMOR_API_KEY:?Set ISOMOR_API_KEY}" &&
curl --request POST "${ISOMOR_API_BASE_URL}/translations" \
  --header "Authorization: Bearer ${ISOMOR_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-001' \
  --data '{
  "file_id": "file_example",
  "target_language": "zh",
  "source_language": "en",
  "pages": "1-3",
  "output_formats": [
    "translated",
    "bilingual"
  ]
}'

响应字段

id / file_idstring: 任务 ID 与来源文件 ID；保存任务 ID 用于后续查询。
statusstring: 首次接收为 queued；幂等重放可能返回任务当前状态。

202 · 响应示例

{
  "id": "job_example",
  "file_id": "file_example",
  "status": "queued"
}

GET/translations/{job_id}

查询任务状态

按持久化任务 ID 查询，可重复读取。queued / running 时遵循 Retry-After 响应头的秒数轮询；succeeded 后取结果，failed 时停止轮询并读取 error。

所需权限: translations:read

请求参数

job_idpath · required: 创建接口返回的任务 ID；不是 file_id。

请求示例

: "${ISOMOR_API_BASE_URL:?Set ISOMOR_API_BASE_URL}" &&
: "${ISOMOR_API_KEY:?Set ISOMOR_API_KEY}" &&
curl --request GET "${ISOMOR_API_BASE_URL}/translations/job_example" \
  --header "Authorization: Bearer ${ISOMOR_API_KEY}"

响应字段

id / file_idstring: 任务及来源文件 ID。
statusenum: queued → running → succeeded 或 failed。succeeded 表示结果已就绪；未提供取消端点。
errorobject | null: 非失败状态为 null；失败时包含 code 和 message，不返回内部堆栈或用户内容。

200 · 响应示例

{
  "id": "job_example",
  "file_id": "file_example",
  "status": "succeeded",
  "error": null
}

GET/translations/{job_id}/results

获取结果文件

仅任务 succeeded 后获取。未就绪返回 409 result_not_ready；失败任务返回 409 job_failed。链接过期后重新请求本接口，不要重新创建翻译。

所需权限: translations:read

请求参数

job_idpath · required: 本人接入身份的已完成任务 ID。

请求示例

: "${ISOMOR_API_BASE_URL:?Set ISOMOR_API_BASE_URL}" &&
: "${ISOMOR_API_KEY:?Set ISOMOR_API_KEY}" &&
curl --request GET "${ISOMOR_API_BASE_URL}/translations/job_example/results" \
  --header "Authorization: Bearer ${ISOMOR_API_KEY}"

响应字段

job_idstring: 该结果所属的任务。
files[].formatenum: translated 或 bilingual，与创建时请求的格式一致。
files[].urlstring · URI: 受控的临时 HTTPS 下载链接；属于敏感访问材料，不写入日志。
files[].expires_atstring · date-time: 链接失效时间，RFC 3339 UTC；失效前下载并妥善保存。

200 · 响应示例

{
  "job_id": "job_example",
  "files": [
    {
      "format": "translated",
      "url": "https://example.com/results/translated.pdf",
      "expires_at": "2026-09-10T12:00:00Z"
    },
    {
      "format": "bilingual",
      "url": "https://example.com/results/bilingual.pdf",
      "expires_at": "2026-09-10T12:00:00Z"
    }
  ]
}

GET/quota

查询 API 额度

查询该 API 接入的额度快照；创建任务时再检查并预留额度。API 额度与 MCP 使用的个人账号额度分别计算。

所需权限: quota:read

请求参数

无路径、查询或请求体参数；仍需 Bearer 认证。

请求示例

: "${ISOMOR_API_BASE_URL:?Set ISOMOR_API_BASE_URL}" &&
: "${ISOMOR_API_KEY:?Set ISOMOR_API_KEY}" &&
curl --request GET "${ISOMOR_API_BASE_URL}/quota" \
  --header "Authorization: Bearer ${ISOMOR_API_KEY}"

响应字段

unit"credits": 额度单位；文字 PDF 每页消耗 1 积分，查询与上传不消耗翻译积分。
limit / used / reserved / remaininginteger ≥ 0: 总授予 / 已结算 / 任务预留 / 可用；remaining = limit − used − reserved，均是当前额度周期的快照。
expires_atdate-time | null: 额度失效时间；null 表示未设置失效时间，不代表无限额度。

200 · 响应示例

{
  "unit": "credits",
  "limit": 100,
  "used": 20,
  "reserved": 10,
  "remaining": 70,
  "expires_at": null
}

错误与重试

错误响应包含 error.code、error.message 与 request_id；排查时提供 request_id，不发送完整 Key、下载链接或文档内容。

{
  "error": {
    "code": "quota_exceeded",
    "message": "The API allowance is insufficient."
  },
  "request_id": "req_example"
}

400invalid_request: 修正缺少的字段、JSON 或幂等键。
401invalid_api_key: 检查凭证是否有效、过期或撤销；不自动重试。
403insufficient_scope: 联系支持开通需要的权限。
404not_found: 核对 ID 及所属接入；其他用户的资源也返回 404。
409idempotency_conflict: 原请求重试保持同键同参数；不同任务使用新键。
409result_not_ready / job_failed: 未就绪继续查询任务；失败读取 error，不循环取结果。
413 / 422file_too_large / unsupported_pdf: 调整文件大小或 PDF 内容；语言和页段参数错误返回 400 invalid_request，不自动重试。
429quota_exceeded: 停止新任务并邮件申请提额；等待几秒不能恢复额度。
403quota_expired: 额度已过期，联系支持续期；已受理任务仍正常处理。
429concurrency_limit / storage_limit: 并发已满时等待任务完成；输入存储额度用满时联系支持。
429rate_limited: 遵循 Retry-After 秒数并退避；创建任务重用幂等键。
503service_unavailable: 指数退避；创建任务必须保留原键，避免重复执行。

幂等窗口为 24 小时：同一接入身份、端点及 Idempotency-Key 对应唯一任务；同键同参数返回原任务，同键不同参数返回 409。创建请求超时或收到 5xx 时，在窗口内仅用原键和原参数重试；超出窗口且不知道任务 ID 时先联系支持，不盲目重建。上传重试可能生成另一文件，但不会发起翻译。

额度与文件边界

API 接入获批后获得初始免费额度，数量和有效期以邮件确认为准。文字 PDF 每页消耗 1 积分。用完后可邮件申请提额，不自动收费。任务创建时预留额度，成功后结算，确认失败后释放预留；查询 /quota 查看可用余额。额度不足时不能创建新任务。

支持文字 PDF、异步单文件翻译和译文／双语 PDF 交付，不包括扫描件、OCR、Office、Webhook、批量提交或取消端点。大小、页数、并发、速率和输入存储额度以 /capabilities 返回值为准；存储额度用满可联系支持。下载链接有有效期，过期后可重新获取；链接失效不等于文件删除。文档文字会发送至 Google Gemini，使用前阅读隐私说明并核验结果。

邮件申请更高额度 ↗