API Reference

PDF 翻译 API

通过译档公开 API 上传 PDF、生成估算、确认翻译任务、轮询状态，并在任务成功后下载译文 PDF。页面是静态文档，接口本身统一走 https://translate.qkfintech.cn 下的 /v1 路径。

认证

所有公开 API 都使用 Bearer Token。请求头固定为 Authorization: Bearer yd_sk_live_...。API key 在网页端 API 管理页创建，完整密钥只在创建或轮换时显示一次。

下载与归因

任务成功后，查询任务响应里的 artifacts 会包含 artifact_id 和 download_url。用 artifact 下载接口获取译文 PDF。所有花费记录会区分 channel=web 和 channel=api。

8 个公开接口

方法 路径 用途
GET GET /v1/me 确认当前 key 所属账户、余额摘要和 key 状态。
POST POST /v1/files 上传 PDF，返回 file_id、文件名、大小和上传状态。
POST POST /v1/translation-estimates 传入 file_id、目标语言和模式，返回预计 tokens、预计积分和余额是否足够。
POST POST /v1/translations 基于 estimate_id 确认任务，必须携带 Idempotency-Key，成功后冻结积分并入队。
GET GET /v1/translations/{translation_id} 查询任务状态、tokens、积分、错误码和 artifacts。
GET GET /v1/translations/{translation_id}/events 查看翻译进度事件。
GET GET /v1/translations/{translation_id}/artifacts/{artifact_id} 下载译文 PDF 产物。任务未成功或 artifacts 为空时不要调用。
GET GET /v1/usage 按时间、渠道、key、任务查询 API/Web 用量归因。

最短调用流程

  1. 1

    检查 key

    调用 GET /v1/me，确认 key 有效、账户余额可读。

  2. 2

    上传 PDF

    用 POST /v1/files 上传本地 PDF，拿到 file_id。

  3. 3

    生成估算

    调用 POST /v1/translation-estimates，检查 can_afford。余额不足时不要确认任务。

  4. 4

    确认任务

    调用 POST /v1/translations，请求头带 Idempotency-Key。同一个 key 不要复用不同 body。

  5. 5

    轮询并下载

    轮询 GET /v1/translations/{translation_id}。当 status=succeeded 且 artifacts 非空时，用 GET /v1/translations/{translation_id}/artifacts/{artifact_id} 下载译文 PDF。

cURL 示例

export YD_API_KEY="yd_sk_live_***"
export YIDOC_API_BASE="${YIDOC_API_BASE:-https://translate.qkfintech.cn}"

curl -sS -H "Authorization: Bearer $YD_API_KEY" "$YIDOC_API_BASE/v1/me"

curl -sS -X POST "$YIDOC_API_BASE/v1/files" \
  -H "Authorization: Bearer $YD_API_KEY" \
  -F "file=@demo.pdf"

curl -sS -X POST "$YIDOC_API_BASE/v1/translation-estimates" \
  -H "Authorization: Bearer $YD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id":"FILE_ID","target_language":"zh-CN","mode":"preserve-layout"}'

curl -sS -X POST "$YIDOC_API_BASE/v1/translations" \
  -H "Authorization: Bearer $YD_API_KEY" \
  -H "Idempotency-Key: job-001" \
  -H "Content-Type: application/json" \
  -d '{"estimate_id":"ESTIMATE_ID"}'

常见错误码

invalid_api_key

Authorization 头缺失、格式错误、key 不存在或已删除。

api_key_disabled

key 已停用，新请求会立即失败。

insufficient_credits

余额不足，确认任务前需要充值。

idempotency_key_required

确认任务缺少 Idempotency-Key。

idempotency_conflict

同一个幂等 key 被不同 body 复用。

file_too_large

PDF 超过上传大小限制。

unsupported_pdf

PDF 无法解析、加密或不适合当前翻译能力。

ocr_required

扫描件需要 OCR，v1 当前不处理 OCR。

下载资料

OpenAPI 3.1 YAML

下载 openapi.yaml。这份文件保留为 API schema 审查和工具导入入口。