字幕翻译接口文档

把已有中文字幕条目翻译成英语或日语，逐条保留标识与时间窗，支持术语表、角色关系、上下文和字数上限。

接口说明

把已有中文字幕条目翻译成英语或日语。不接收音视频地址。

方法与路径	产品编码	说明
`POST /api/audio_subtitles_translate`	`audio_subtitles_translate`	提交翻译任务
`GET /api/tasks/{request_id}`	—	查询任务。音频字幕和智能字幕也使用此接口

本接口是异步的。受理后用任务号查询结果；请求里带了回调地址时，任务结束会再 POST 同一份结果。不填回调地址也可以提交。

环境	根地址
测试	`https://test-star-api.aiaibase.com`
正式	`https://star-api.aiaibase.com`

路径接在根地址后面。例如测试环境提交字幕翻译：

text

POST https://test-star-api.aiaibase.com/api/audio_subtitles_translate

请求体为 JSON，Content-Type: application/json。单次请求体不超过 1 MB。认证只使用请求头，不需要额外的 Secret：

text

Authorization: Bearer {API Key}

{API Key} 为商户密钥全文。

音频字幕固定从音轨识别生成源字幕和译文。智能字幕会自动选择字幕轨、画面字幕或语音识别。若只需翻译已经分好条的中文字幕，请使用本接口。

通用约定

所有响应都是同一结构。判断业务结果以 success 和 error.code 为准，HTTP 状态码会同时返回。

字段	类型	说明
`success`	bool	受理成功、处理中、处理成功为 `true`；失败为 `false`
`data`	object	成功或处理中的业务数据。失败时不返回
`message`	string	失败说明。成功时通常不返回
`error`	object	失败时的错误
`meta.request_id`	string	平台任务号。后续查询、回调都用这个值
`meta.timestamp`	string	响应时间，RFC3339，例如 `2026-10-20T22:02:29.735909+08:00`

错误对象：

字段	类型	说明
`error.code`	int	业务错误码
`error.message`	string	错误说明
`error.details`	array	参数错误时给出字段。每项含 `field`、`message`

调用方请求号：

字段可用 client_request_id，也可用别名 request_id。两者都传时以 client_request_id 为准。
这是调用方自己的单号，和响应里的 meta.request_id 不是同一个值。
同一密钥下，相同调用方请求号且请求体完全一致时，返回上一次的受理或结果，不会再次受理。
同一密钥下，调用方请求号相同但请求体不同，返回 HTTP 409，业务码 4003，说明「资源冲突」。
填写了 notice_url 或 callback_url 时，必须带调用方请求号。

请求参数

字段	必填	类型	说明
`source_language`	是	string	原文语种。目前只支持 `zh`
`target_languages`	是	string[] 或 string	目标语种。支持 `en`、`ja`，至少一个，不能重复。字符串可用逗号或换行分隔
`cues`	是	array	待翻译字幕，1 到 3000 条
`context`	否	array	上下文，最多 3000 条。只作语境，不翻译、不计入结果
`glossary`	否	object 或 array	术语表。译法可含 `en`、`ja`
`reference`	否	object	场景和角色关系。`speaker_id` 对应条目里的说话人
`notice_url`	否	string	完成后的回调地址，`http` 或 `https`
`callback_url`	否	string	`notice_url` 的别名
`client_request_id`	条件	string	调用方请求号。填写回调地址时必填
`request_id`	条件	string	`client_request_id` 的别名

条目对象里出现未列出的字段时，返回参数错误。

待翻译条目

cues 每项：

字段	必填	类型	说明
`cue_id`	是	string	条目标识，本次请求内唯一，不能为空白
`start_ms`	是	int	开始时间，非负整数毫秒
`end_ms`	是	int	结束时间，整数毫秒，必须大于 `start_ms`
`text`	是	string	中文原文，不能为空白，最多 500 字
`source_cue_ids`	否	array	来源条目，原样保留。允许 `null`
`max_chars`	否	object	各语种字数上限，键只能是 `en`、`ja`，值为正整数。超长不截断
`speaker_id`	否	string	说话人标识，原样保留。允许 `null`

上下文

context 每项只允许 start_ms、end_ms、text、speaker_id。时间和文本约束与 cues 相同。不能带 cue_id、source_cue_ids、max_chars。

术语表

术语表字段与音频字幕相同。数组条目的译法放在 targets，例如 {"en": "Master", "ja": "師匠"}。

数组写法，每项：

字段	类型	说明
`source`	string	术语原文，必填
`en`	string	英文译法
`ja`	string	日文译法
`zh`	string	中文
`aliases`	string[]	别名
`type`	string	`person`、`place`、`sect`、`phrase`。可省略
`retranslate`	bool	是否重新翻译
`targets`	object	目标译法，例如 `{"en": "Master", "ja": "師匠"}`

对象写法：

字段	类型	说明
`version`	string	术语表版本，必填
`entries`	array	条目。原文用 `zh`，不再用 `source`。其余字段与数组写法相同

场景与角色关系

reference：

字段	类型	说明
`scene`	string	场景说明
`relations`	array	角色关系

relations 每项：

字段	类型	说明
`speaker_id`	string	说话人标识，必填。对应条目里的 `speaker_id`
`listener_id`	string	听话人标识
`address`	string	称呼
`register`	string	语体，例如 `敬语`

受理返回

HTTP 200。此时任务尚未完成。

字段	类型	说明
`data.status`	string	固定为 `accepted`
`data.client_request_id`	string	调用方请求号。未传时为空字符串
`meta.request_id`	string	平台任务号，用于查询

json

{
  "success": true,
  "data": {
    "status": "accepted",
    "client_request_id": "ep01-translate"
  },
  "meta": {
    "request_id": "42642e01-2e33-4265-b6af-206eed371fff",
    "timestamp": "2026-10-20T22:02:29.735909+08:00"
  }
}

请求示例

bash

curl -X POST 'https://test-star-api.aiaibase.com/api/audio_subtitles_translate' \
  -H 'Authorization: Bearer {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_language": "zh",
    "target_languages": ["en", "ja"],
    "cues": [
      {
        "cue_id": "c012",
        "start_ms": 90120,
        "end_ms": 95020,
        "text": "师父，我要动身了。",
        "speaker_id": "S1",
        "source_cue_ids": [12, 13],
        "max_chars": {"en": 84, "ja": 26}
      }
    ],
    "context": [
      {"start_ms": 86000, "end_ms": 89800, "text": "船要开了。", "speaker_id": "S2"}
    ],
    "glossary": {
      "version": "v1",
      "entries": [{"zh": "师父", "en": "Master", "ja": "師匠", "type": "person"}]
    },
    "reference": {
      "scene": "辞行",
      "relations": [{"speaker_id": "S1", "listener_id": "S2", "address": "师父", "register": "敬语"}]
    },
    "client_request_id": "ep01-translate",
    "notice_url": "https://your.host/hook"
  }'

查询任务

字幕翻译、音频字幕和智能字幕共用。只能查询当前密钥自己受理的任务，查不到或密钥不匹配时返回 HTTP 404，业务码 1000。

方法：GET
路径：/api/tasks/{request_id}
request_id：受理响应里的 meta.request_id

处理尚未结束时 HTTP 200，data.status 仍为 accepted，并带 client_request_id。成功后 HTTP 200，data 换成下方翻译结果。失败时 success 为 false，HTTP 状态和错误码为失败原因。

bash

curl 'https://test-star-api.aiaibase.com/api/tasks/42642e01-2e33-4265-b6af-206eed371fff' \
  -H 'Authorization: Bearer {API Key}'

处理中：

json

{
  "success": true,
  "data": {
    "status": "accepted",
    "client_request_id": "ep01-translate"
  },
  "meta": {
    "request_id": "42642e01-2e33-4265-b6af-206eed371fff",
    "timestamp": "2026-10-20T22:02:31.000000+08:00"
  }
}

成功结果

查询成功和成功回调的 data 来自翻译结果文件，并写入 client_request_id、out_data、upstream_task_id。

字段	类型	说明
`client_request_id`	string	调用方请求号
`results`	array	按提交顺序返回，保留 `cue_id`、`start_ms`、`end_ms`
`counts`	object	各目标语种的成功、失败条数
`effective.glossary`	bool	术语表是否有条目进入翻译
`effective.reference`	bool	场景或某条关系是否进入提示词
`stats`	object	条数、字数和耗时
`model_version`	string	翻译模型版本
`out_data`	string[]	结果 JSON、源语言 SRT 和各目标语种 SRT 的地址
`upstream_task_id`	string	上游任务号

每条结果保留 cue_id、start_ms、end_ms。每个目标语种成功时 status 为 succeeded，并带译文 text 和 actual_chars。失败时 status 为 failed，text 为 null，错误为 missing 或 empty。

风险标记包括 source_leak、glossary_miss、over_limit。超长译文不截断。日文计字不计空白和句末一个标点，其余语种按全部字符计。语种在结果中的分组以结果文件为准。任务完成时同时看 counts 里的失败条数和每条 status。

counts.{语种}：

字段	类型	说明
`succeeded`	int	成功条数
`failed`	int	失败条数

json

{
  "success": true,
  "data": {
    "client_request_id": "ep01-translate",
    "model_version": "PanShi-MT-1.0",
    "upstream_task_id": "3e31e8a7-3ab1-4f4c-8c08-d966ec006d49",
    "out_data": [
      "https://cdn.example.com/subtitle/ep01.translate.json",
      "https://cdn.example.com/subtitle/ep01.zh.srt",
      "https://cdn.example.com/subtitle/ep01.en.srt"
    ],
    "results": [
      {
        "cue_id": "c012",
        "start_ms": 90120,
        "end_ms": 95020
      }
    ],
    "counts": {
      "en": {"succeeded": 1, "failed": 0},
      "ja": {"succeeded": 1, "failed": 0}
    },
    "effective": {"glossary": true, "reference": true},
    "stats": {"elapsed_ms": 4200}
  },
  "meta": {
    "request_id": "42642e01-2e33-4265-b6af-206eed371fff",
    "timestamp": "2026-10-22T16:50:00+08:00"
  }
}

回调

请求体带 notice_url 或 callback_url，且任务进入成功或失败后，本服务向该地址发起 POST。没有回调地址时不会 POST。

项	值
方法	`POST`
`Content-Type`	`application/json`
`User-Agent`	`star-openapi`
请求体	与 `GET /api/tasks/{request_id}` 的响应 JSON 相同
成功条件	回调地址返回 HTTP 2xx
重试	非 2xx 或连接失败时，间隔 30 秒重试，最多 4 次
超时	单次回调等待 10 秒

任务提交后超过 24 小时仍未完成，记为失败，业务码 3601，说明「字幕任务已超过 24 小时」。若当时带了回调地址，失败结果也会按上面的规则回调。

成功回调的请求体就是上一节的成功 JSON。失败回调示例：

json

{
  "success": false,
  "message": "上游处理失败",
  "error": {
    "code": 3600,
    "message": "上游处理失败"
  },
  "meta": {
    "request_id": "42642e01-2e33-4265-b6af-206eed371fff",
    "timestamp": "2026-10-20T22:04:10.000000+08:00"
  }
}

接收方按 success 区分成功和失败。成功时读取 data，失败时读取 error.code 与 error.message。用 meta.request_id 或 data.client_request_id 对应自己的业务单。

错误码

HTTP	业务码	说明	常见原因
400	1101	JSON格式错误	请求体不是合法 JSON
400	1102	缺少必要的请求头	没有 `Authorization`
400	1001	参数错误	音视频地址、来源、热词、切段、术语、角色关系不合法。字段在 `error.details`
400	4102	缺少必填项	未传 `source_language`，或填了回调地址却没有调用方请求号
400	4107	地址不合法	`video_url`、`audio_url`、`notice_url` 不是 `http` 或 `https`
401	5003	认证信息无效	API Key 错误
401	5301	令牌已过期	密钥已过期
401	5304	令牌已被撤销	密钥已停用或已重置
403	5103	账户已被禁用	商户已停用
403	5104	账户已被暂停	商户已暂停
403	5204	资源访问被拒绝	密钥没有该接口权限
404	1000	资源未找到	任务号不存在，或不属于当前密钥
409	4003	资源冲突	同一调用方请求号对应了不同请求体
413	1004	请求实体过大	请求体超过 1 MB
402	9903	余额不足	预付商户现金和剩余透支不足以支付本次调用
429	9902	配额已超出	套餐额度用尽，或触发接口用量上限
429	5705	请求过于频繁	超过密钥或接口的频率限制
500	1500	服务器内部错误	未归类的服务端错误
502	3600	上游处理失败	字幕任务提交或处理失败。说明可能是上游返回的具体原因
503	1502	服务暂不可用	字幕通道未配置，或价格未配置
504	3601	上游处理超时	提交超时，或任务超过 24 小时仍未完成

参数错误示例：

json

{
  "success": false,
  "message": "video_url 和 audio_url 必须二选一",
  "error": {
    "code": 1001,
    "message": "video_url 和 audio_url 必须二选一",
    "details": [
      {
        "field": "video_url",
        "message": "video_url 和 audio_url 必须二选一"
      }
    ]
  },
  "meta": {
    "request_id": "3b3779be-b27d-4f51-99e0-a1b1c7e6bf6c",
    "timestamp": "2026-10-22T04:40:00+08:00"
  }
}

认证失败示例：

json

{
  "success": false,
  "message": "认证信息无效",
  "error": {
    "code": 5003,
    "message": "认证信息无效"
  },
  "meta": {
    "request_id": "7c1a0e2d-1111-4222-8333-444455556666",
    "timestamp": "2026-10-22T04:40:00+08:00"
  }
}