OPENAPI v1

API 文档

把商品翻译接进你自己的系统 —— 两个接口就能跑通：提交任务、查询结果。

快速开始

三步跑通一次调用。想先不写代码，可以直接用工作台的接口测试页发一次请求。

1
在工作台创建一把 API Key
创建时会显示一次完整明文，务必当场保存 —— 之后再也取不到。可以同时设置来源 IP 白名单。
2
调用提交接口，拿到任务号
带上 X-API-Key 和 Idempotency-Key，POST 到 /openapi/v1/jobs。建议先用 dry_run 演练一次验证参数。
3
用任务号查询结果
GET /openapi/v1/jobs/{job_id}。也可以配置回调，任务完成后由我们主动通知你。

鉴权

每个请求都要带 X-API-Key 请求头，值是你在工作台创建的完整 Key（形如 jfk_ 开头的一串）。

X-API-Key: jfk_AbCdEfGh...

Key 明文只出现一次

我们库里只存 Key 的 SHA256 指纹和前 12 个字符，全系统唯一一次能拿到完整明文，是创建它的那一刻。关掉那个弹窗就再也取不回来 —— 没保存好只能作废重建。

IP 白名单

每把 Key 可以单独设来源 IP 白名单，留空表示不限。设了之后，来自名单外的请求会被拒回 AUTH_IP_NOT_ALLOWED。

工作台的接口测试不受白名单限制

测试台的请求是从 JCT 的服务器发出的，不是你的服务器，所以它会跳过白名单校验。 测试台通 ≠ 真实调用通：真正接入前请确认你服务器的出口 IP 在名单里。

停用

停用是单向的，不可恢复，需要恢复只能重新生成一把。停用后这把 Key 立刻无法提交新任务（会收到 AUTH_KEY_DISABLED），但已经在跑的任务会照常完成、结果回调也照常发送。

Idempotency-Key（必读）

提交接口的必填请求头

POST /openapi/v1/jobs 要求必须带 Idempotency-Key，少了这个头会直接 400。工作台的接口测试页替你自动生成了它，表单上看不到 —— 所以很容易在自己写对接代码时漏掉，上线第一天每个请求都失败。

必填

提交接口缺这个头会直接返回 400

每个新任务换新值

提交一个新任务就生成一个新的键，不要复用

超时重发用同一个值

这是它唯一的用途：让重发不会变成重复下单

它的意义就在超时重发这一步：网络超时时你并不知道后端到底收没收到。带同一个 Idempotency-Key 重发，命中的是幂等重放 —— 拿回原来那一单， 不会产生新任务，也不会再扣一次额度。如果每次都随机生成一个新值，超时重发就是重复扣费。

注意：演练请求（dry_run: true）在占用幂等键之前就直通返回了， 不占用幂等键。所以同一个值用于演练可以反复跑，这不代表幂等没生效。

查询接口不落幂等，不需要带这个头。

POST/openapi/v1/jobs

提交翻译任务

请求头

名称	必填	说明
`X-API-Key`	必填	工作台创建的完整 Key 明文
`Idempotency-Key`	必填	幂等键，见上一节；缺失或为空都会 400
`Content-Type`	必填	application/json

请求体

字段	类型	说明
`service_code`	string	auto_translate（自动翻译）或 refined_image（精细图片处理）
`source_lang`	string	源语言。目前只支持 zh
`target_lang`	string	目标语言。目前只支持 ko；其它组合返回 INPUT_LANG_UNSUPPORTED
`tier`	string	standard 或 premium
`dry_run`	boolean	true 为演练，只校验不执行、不扣额度
`items`	array	待处理条目，至少一条
`items[].client_item_id`	string	你自己的条目标识，必填，用于把结果对回你的商品
`items[].kind`	string	text 或 image
`items[].text`	string	kind 为 text 时必填
`items[].image_url`	string	kind 为 image 时必填，需是我们可访问的地址

不接受未知字段

请求体会被严格解析，多带一个没定义的字段就是 400。另外文本条目不要带 image_url、图片条目不要带 text。

示例

curl -X POST 'https://<你的域名>/openapi/v1/jobs' \
  -H 'X-API-Key: jfk_AbCdEfGh...' \
  -H 'Idempotency-Key: 每个新任务换一个新值' \
  -H 'Content-Type: application/json' \
  -d '{
  "service_code": "auto_translate",
  "source_lang": "zh",
  "target_lang": "ko",
  "tier": "standard",
  "dry_run": true,
  "items": [
    {
      "client_item_id": "sku-001",
      "kind": "text",
      "text": "人体黄金曲度设计 舒适支撑贴合"
    },
    {
      "client_item_id": "sku-002",
      "kind": "image",
      "image_url": "https://example.com/main.jpg"
    }
  ]
}'

响应

受理成功返回 202（排队和演练都算受理），响应体里带 26 位的 job_id；响应头里有 X-Request-Id，排查问题时请一并提供。

HTTP/1.1 202 Accepted
X-Request-Id: 01JBX6Q2K8ZP4M7N3V5T9W1R0C

{
  "job_id": "01JBX6Q2K8ZP4M7N3V5T9W1R0C"
}

完整响应体字段以实际返回为准 —— 在接口测试页发一次请求就能看到原始响应。

GET/openapi/v1/jobs/{job_id}

查询任务状态

用提交时拿到的 job_id 查这一单的处理状态与结果。只需要 X-API-Key，不需要幂等键。

curl -X GET 'https://<你的域名>/openapi/v1/jobs/01JBX6Q2K8ZP4M7N3V5T9W1R0C' \
  -H 'X-API-Key: jfk_AbCdEfGh...'

演练任务查不到

演练（dry_run: true）不落库，它也会返回一个形状一致的任务号，但拿这个号去查会得到 NOT_FOUND_JOB —— 这是正常的，不是查询接口坏了。

演练模式

请求体里把 dry_run 设为 true，用来在不花钱的前提下验证参数是否合法。

不占用幂等键 —— 同一个 Idempotency-Key 可以反复演练
不冻结、不扣除额度
不落库、不进处理队列
会返回一个形状一致的任务号，但这个号查不到任何东西

确认参数没问题后，把 dry_run 改成 false 就是真实提交。

错误处理

失败时返回统一的错误信封，按 code 分支处理，不要去匹配 message 文案。

{
  "code": "INPUT_LANG_UNSUPPORTED",
  "message": "暂不支持该语言方向",
  "request_id": "01JBX6Q2K8ZP4M7N3V5T9W1R0C"
}

code	含义
`INPUT_INVALID_PARAM`	参数不合法，包括缺必填字段、带了未定义字段
`INPUT_LANG_UNSUPPORTED`	语言方向不支持。目前仅支持 zh → ko
`AUTH_KEY_DISABLED`	这把 Key 已停用。停用不可恢复，请改用新的 Key
`AUTH_IP_NOT_ALLOWED`	来源 IP 不在这把 Key 的白名单内
`NOT_FOUND_JOB`	查不到该任务号。演练产生的任务号必然落在这里

request_id 请记进你自己的日志。来找我们排查时带上它，能直接定位到那一次请求。

回调验签

任务完成后我们会向你配置的地址发回调。验证这个回调是不是我们发的，用的签名密钥 不另外下发 —— 由你自己从 API Key 算出来：

签名密钥 = sha256(完整的 API Key) 的小写十六进制

# 例如在 shell 里：
printf '%s' 'jfk_AbCdEfGh...' | shasum -a 256

也就是对完整 Key 做一次 SHA256，取小写十六进制。所以你只需要保管好那一串 Key，不存在"第二串密钥"。

快速开始

在工作台创建一把 API Key

调用提交接口，拿到任务号

用任务号查询结果

鉴权

IP 白名单

停用

Idempotency-Key（必读）

提交翻译任务

请求头

请求体

示例

响应

查询任务状态

演练模式

错误处理

回调验签