智能字幕接口文档

来源固定为自动：先找字幕轨，再读画面字幕，都没有再从音轨识别。可传入已有源字幕，完成后查询或回调。

接口说明

提交音频或视频地址，生成源语种字幕，并按目标语种翻译。来源固定为自动：先找字幕轨，再读画面字幕，都没有再从音轨识别。本接口是异步的。受理后用任务号查询结果；请求里带了回调地址时，任务结束会再 POST 同一份结果。

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

不填回调地址也可以提交，结果用查询接口获取。

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

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

text

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

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

text

Authorization: Bearer {API Key}

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

需要固定从音轨识别时，使用音频字幕。不传 target_languages 时只返回源字幕。若只需翻译已经分好条的字幕，请使用字幕翻译。

通用约定

所有响应都是同一结构。判断业务结果以 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 时，必须带调用方请求号。

请求参数

参数与音频字幕相同，并可以另传已有源字幕。

字段	必填	类型	说明
`video_url`	二选一	string	视频地址，`http` 或 `https`。与 `audio_url` 只能传一个
`audio_url`	二选一	string	音频地址，`http` 或 `https`
`source_language`	是	string	原文语种。目前只支持 `zh`
`target_languages`	否	string[]	目标语种。支持 `en`、`ja`，不能重复。不传则只返回源字幕
`source_cues`	否	array	已有源字幕
`source_srt`	否	string	`source_cues` 的别名，SRT 文本
`hotwords`	否	string[]	热词。最多 100 个，每个最多 20 个字
`speakers`	否	object	说话人
`segmentation`	否	object	切段覆盖项，只传需要改的字段
`glossary`	否	object 或 array	术语表。有目标语种时参与翻译
`reference`	否	object	场景和角色关系
`notice_url`	否	string	完成后的回调地址，`http` 或 `https`
`callback_url`	否	string	`notice_url` 的别名。`notice_url` 为空时才使用
`client_request_id`	条件	string	调用方请求号。填写回调地址时必填
`request_id`	条件	string	`client_request_id` 的别名

对象内部出现未列出的字段时，返回参数错误。

已有源字幕

source_cues 为对象数组。每项只允许 start_ms、end_ms、text。时间为整数毫秒，start_ms >= 0 且 start_ms < end_ms，text 不能为空，条数 1 到 3000。source_srt 为 SRT 文本，按其中 --> 的条数计数。

时间行格式示例：

text

1
00:00:06,740 --> 00:00:09,380
货船靠岸了。

说话人

字段	类型	说明
`enabled`	bool	是否区分说话人
`num_speakers`	int	说话人数，0 到 20。0 表示自动判断

切段参数

segmentation 只允许下列字段，超出范围返回参数错误：

字段	类型	范围
`skip_silence`	bool	是否跳过静音
`min_silence_s`	number	0.2 到 5，单位秒
`speech_pad_ms`	int	0 到 1000
`min_speech_ms`	int	0 到 2000
`merge_gap_ms`	int	0 到 10000
`max_cue_duration_ms`	int	1000 到 15000
`max_cue_gap_ms`	int	0 到 3000
`max_cue_chars`	int	8 到 80
`silence_threshold`	string	`-60dB` 到 `-20dB`，必须带 `dB` 后缀，例如 `-40dB`

术语表

glossary 有两种写法。

数组写法，每项：

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

对象写法：

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

场景与角色关系

reference：

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

relations 每项：

字段	类型	说明
`speaker_id`	string	说话人标识，必填
`listener_id`	string	听话人标识
`address`	string	称呼
`register`	string	语体，例如 `casual`

受理返回

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

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

json

{
  "success": true,
  "data": {
    "status": "accepted",
    "client_request_id": "ep07-auto"
  },
  "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_auto' \
  -H 'Authorization: Bearer {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "video_url": "https://cdn.example.com/ep07.mp4",
    "source_language": "zh",
    "target_languages": ["en", "ja"],
    "glossary": [{"source": "航线", "en": "route", "ja": "航路"}],
    "client_request_id": "ep07-auto",
    "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": "ep07-auto"
  },
  "meta": {
    "request_id": "42642e01-2e33-4265-b6af-206eed371fff",
    "timestamp": "2026-10-20T22:02:31.000000+08:00"
  }
}

成功结果

查询成功，以及成功回调的 data，字段如下。client_request_id 由本服务写入，其余字段来自字幕结果。

字段	类型	说明
`client_request_id`	string	调用方请求号
`model_version`	string	模型版本，例如 `subtitle-v1.0`
`upstream_task_id`	string	字幕任务号
`out_data`	string[]	结果文件地址，通常包含一份 JSON 和各语种 SRT
`source.language`	string	源语种，例如 `zh`
`source.text_source`	string	实际采用的来源，例如 `subtitle_track`、`ocr` 或 `asr`
`source.cues`	array	源字幕条目
`translations`	object	按目标语种分组的译文。未请求翻译时可能没有
`counts`	object	各目标语种的成功、失败条数
`stats`	object	时长与条数统计

source.cues 每项：

字段	类型	说明
`index`	int	序号，从 1 开始
`start_ms`	int	开始时间，毫秒
`end_ms`	int	结束时间，毫秒
`text`	string	字幕文本
`risk_flags`	array	风险标记。没有时为空数组

translations.{语种} 每项在源字幕字段之外还有：

字段	类型	说明
`status`	string	该条翻译状态，成功为 `succeeded`
`actual_chars`	int	该条译文字数

counts.{语种}：

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

stats：

字段	类型	说明
`audio_duration_ms`	int	音频时长，毫秒
`cue_count`	int	字幕条数
`elapsed_ms`	int	处理耗时，毫秒
`source_chars`	int	源字幕字数
`target_chars`	object	各目标语种字数，例如 `{"en": 19}`

json

{
  "success": true,
  "data": {
    "client_request_id": "ep07-auto",
    "model_version": "subtitle-v1.0",
    "upstream_task_id": "bb8f885f-e0da-4dda-b06d-9aa6307e1e46",
    "out_data": [
      "https://cdn.example.com/subtitle/ep07.json",
      "https://cdn.example.com/subtitle/ep07.zh.srt",
      "https://cdn.example.com/subtitle/ep07.en.srt"
    ],
    "source": {
      "language": "zh",
      "text_source": "asr",
      "cues": [
        {
          "index": 1,
          "start_ms": 6740,
          "end_ms": 9380,
          "text": "货船靠岸了。",
          "risk_flags": []
        }
      ]
    },
    "translations": {
      "en": [
        {
          "index": 1,
          "start_ms": 6740,
          "end_ms": 9380,
          "text": "The cargo ship has docked.",
          "status": "succeeded",
          "actual_chars": 25,
          "risk_flags": []
        }
      ]
    },
    "counts": {
      "en": {"succeeded": 1, "failed": 0}
    },
    "stats": {
      "audio_duration_ms": 12416,
      "cue_count": 1,
      "elapsed_ms": 64355,
      "source_chars": 6,
      "target_chars": {"en": 25}
    }
  },
  "meta": {
    "request_id": "42642e01-2e33-4265-b6af-206eed371fff",
    "timestamp": "2026-10-20T22:03:50.341549+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"
  }
}