文本翻译 API
将一段文本翻译为目标语言,支持上下文和术语表。
在 API 控制台 创建 API Key,通过 Authorization: Bearer <API_KEY> 请求头认证。运行示例前,在服务端环境中设置 LECSYNC_API_KEY。API Key 应保存在服务端。
发起请求
POST /v1/translate
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
text | string | 是 | 非空文本字符串,最多 2,000 个 Unicode 字符。 |
target_lang | string | 是 | 目标语言代码,例如 zh、en、ja。 |
source_lang | string | 否 | 源语言,默认 auto。短文本或含义不明确时建议指定。 |
context | string | 否 | 背景信息,最多 2,000 个 Unicode 字符。 |
terms | object[] | 否 | 最多 20 对 {source, target} 术语,每侧最多 120 个 Unicode 字符。 |
model | string | 否 | 可选模型标识,默认使用表中列出的值。 translate-default. |
响应
以下示例展示主要响应字段,实际响应还可能包含用量元数据。
| 字段 | 说明 |
|---|---|
request_id | 请求标识,用于查询状态和排查问题,请保存。 |
status | accepted、processing、succeeded、failed 或 cancelled。 |
text | 翻译后的文本。 |
source_lang | 源语言,默认 auto。短文本或含义不明确时建议指定。 |
target_lang | 目标语言代码,例如 zh、en、ja。 |
unchanged | 源语言与目标语言相同时为 true,text 原样返回。 |
result_expires_at | ISO 8601 格式的结果到期时间;结果尚未生成时可为 null。 |
结果查询与重试
每次新调用传入 Idempotency-Key,值为 1–128 个可见 ASCII 字符。保存该键;响应丢失时,使用相同键和相同参数重试。同键不同参数返回 409 IDEMPOTENCY_CONFLICT。请求仍在处理时,重复调用只返回已有状态。使用新键会创建新请求。
成功结果默认保留 24 小时。通过 GET /v1/requests/{request_id} 查询,保存的正文位于 result 字段中;重复提交已成功的 POST 也使用这一结构。到期后返回 410 RESULT_EXPIRED,具体到期时间以 result_expires_at 为准。
限制与用量
按源文本字符数计量,上下文和术语不计入用量。同语言请求仍按源文本计量。
usage.charge_cents 为本次费用,以美分十进制字符串表示。
通过 GET /v1/models 查询当前可用的模型、语言、限制、价格及结果保留时长。
错误处理
HTTP 错误响应包含 error、request_id,响应头中也有 X-Request-Id。排查问题时请提供该标识。
| HTTP | error | 处理方式 |
|---|---|---|
| 401 | UNAUTHORIZED | 检查 API Key 是否有效。 |
| 402 | INSUFFICIENT_BALANCE | 检查 API 余额后重试。 |
| 503 | ADMISSION_DISABLED | 当前账号暂不可使用该服务。 |
| 409 | IDEMPOTENCY_CONFLICT | 查询已有请求;不同输入请使用新键。 |
| 410 | RESULT_EXPIRED | 结果已过期,需要时重新提交。 |
| 422 | INVALID_INPUT / INVALID_IDEMPOTENCY_KEY / PARAMETER_CONFLICT / CAPABILITY_UNAVAILABLE | 检查字段名称、类型及必填参数。 |
| 422 | UNSUPPORTED_LANGUAGE / LANGUAGE_UNDETERMINED | 使用支持的语言;自动检测失败时指定 source_lang。 |
| 429 | RESOURCE_LIMIT | 按 Retry-After 等待后重试。 |
| 503 | MODEL_UNAVAILABLE / SERVICE_UNAVAILABLE | 查询已有请求状态,再决定是否重试。 |
| 504 | DEADLINE_EXCEEDED | 先查询请求状态,再决定是否新建请求。 |