字幕压制接口文档

把字幕文本烧进视频画面,输出新的 MP4。异步受理,成功后查询或回调取成片地址。

把字幕文本烧进视频画面,输出一个新的 MP4。不提供字幕轨,也不做翻译。成品烧在画面上,无法再关闭。

一次压制是一次异步任务:提交后拿到任务号,再轮询到 succeeded 或失败;请求里带了 notify_url 时,任务结束会再 POST 同一份结果。

方法与路径说明
POST /api/subtitle_render提交字幕压制
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/subtitle_render

健康检查:GET {根地址}/public/health,返回 HTTP 200 即可用。

请求体为 JSON,Content-Type: application/json。单次请求体不超过 1 MB。认证只使用请求头:

text
Authorization: Bearer {API Key}

{API Key} 由星鉴开通,开通时会同时开通字幕压制的产品权限。Key 只能放在服务端。

需要从音轨识别字幕时,使用音频字幕。需要自动选择字幕轨、画面字幕或语音识别时,使用智能字幕。只翻译已经分好条的字幕时,使用字幕翻译。本接口只负责把已有字幕烧进画面。

所有响应都是同一结构。

字段类型说明
successbool受理成功、处理中、处理成功为 true;失败为 false
dataobject成功或处理中的业务数据
messagestring失败说明
errorobject失败时的错误。含 code、message,参数错误时还有 details
meta.request_idstring平台任务号。查询任务用这个值
meta.timestampstring响应时间,例如 2026-11-03T08:20:36Z
json
{
  "success": false,
  "message": "缺少视频链接",
  "error": {
    "code": 4102,
    "message": "缺少视频链接",
    "details": [{ "field": "video_url", "message": "缺少视频链接" }]
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

调用方请求号:

  • 字段是 client_request_id。强烈建议每次提交都带,便于重试和查询。
  • 这是调用方自己的单号,和响应里的 meta.request_id 不是同一个值。
  • 同一密钥下,相同调用方请求号且请求体完全一致时,返回原任务,不会重复扣费。
  • 同一密钥下,调用方请求号相同但请求体不同,返回 HTTP 409,业务码 4003。
  • 填写了 notify_url 时,必须带调用方请求号。
  • 不传调用方请求号也能提交,任务号由服务端生成,但无法按请求号幂等重试。

  • 方法:POST
  • 路径:/api/subtitle_render

请求参数

字段必填类型说明
video_url是string视频地址,http 或 https,公网可直接下载,不超过 2 GB
cues是array字幕条目,1–3000 条
cues[].start_ms是int开始时间,毫秒,大于等于 0
cues[].end_ms是int结束时间,毫秒,必须大于 start_ms
cues[].text是string字幕正文,1–500 字。超长请拆条
cues[].top_text否string顶部附加文字。渲染效果以上游输出为准
style否object 或 string样式。可传对象,也可传 JSON 字符串
style.font_size否stringsmall、medium、large,默认 medium
style.font否stringsans、serif,默认 sans
cover否object 或 string封面遮挡。可传对象,也可传 JSON 字符串
cover.mode否stringnone、band、blur,默认 none
cover.region.top否number顶部遮挡比例,0–1
cover.region.bottom否number底部遮挡比例,0–1
notify_url否string回调地址,http 或 https。传入后 client_request_id 必填
client_request_id条件string调用方请求号。填写回调地址时必填

视频地址必须是公网直链。需要登录或防盗链的地址会下载失败。style、cover 传字符串时必须是合法 JSON。

受理返回

HTTP 200。此时成片还没生成。meta.request_id 就是后续查询用的任务号。

json
{
  "success": true,
  "data": {
    "status": "accepted",
    "client_request_id": "order-20261103-0001"
  },
  "meta": {
    "request_id": "0f2022a3-4dae-4643-a399-95c01b991d81",
    "timestamp": "2026-11-03T08:20:36Z"
  }
}

请求示例

bash
curl -X POST 'https://test-star-api.aiaibase.com/api/subtitle_render' \
  -H 'Authorization: Bearer {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "video_url": "https://media.w3.org/2010/05/sintel/trailer.mp4",
    "cues": [
      {"start_ms": 1000, "end_ms": 4000, "text": "第一句字幕"},
      {"start_ms": 4200, "end_ms": 8000, "text": "第二句字幕"}
    ],
    "style": {"font_size": "medium", "font": "sans"},
    "cover": {"mode": "none"},
    "client_request_id": "order-20261103-0001",
    "notify_url": "https://your-domain.com/callback/subtitle"
  }'

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

状态从 accepted 进入处理,成功为 succeeded,失败时整段响应 success 为 false。内部的 running 对外也返回 accepted。

建议 3–5 秒轮询一次。常见成片时间 1–5 分钟,按视频时长放宽超时。任务超过 24 小时仍未完成,会被判失败,业务码在 3600 这一档。

处理中:

json
{
  "success": true,
  "data": {
    "status": "accepted",
    "client_request_id": "order-20261103-0001"
  }
}

成功:

json
{
  "success": true,
  "data": {
    "status": "succeeded",
    "out_data": ["https://images.example.com/…/subtitle_render/xxxx.mp4"],
    "upstream_task_id": "e6eecd7a-d418-4544-b2fc-79804b7f7214",
    "client_request_id": "order-20261103-0001"
  }
}

out_data 是成品 MP4 地址,通常 1 个。链接由上游存储提供,拿到后尽快转存。

失败:

json
{
  "success": false,
  "message": "上游处理失败",
  "error": { "code": 3600, "message": "上游处理失败" }
}

提交时传了 notify_url,任务进入终态后星鉴会 POST 到该地址。请求体与查询任务的响应相同。回调丢失时,仍用查询接口兜底。

项值
方法POST
Content-Typeapplication/json
User-Agentstar-openapi
请求体与 GET /api/tasks/{request_id} 的响应 JSON 相同
成功条件回调地址返回 HTTP 2xx
重试非 2xx 视为失败,间隔 30 秒,最多 4 次

回调可能重复投递。用 meta.request_id 或 client_request_id 做幂等。

HTTP业务码说明处理
4001001字段不支持或参数非法看 error.details[].field
4131004请求实体过大请求体不超过 1 MB,cues 不超过 3000 条
4001101JSON 格式错误检查请求体
4011102缺少请求头加 Authorization
5031502服务暂不可用稍后重试
5023600上游处理失败可重试。换 client_request_id,或排障后重提
4094003同一调用方请求号,请求体不同换请求号,或把请求体改回第一次
4004102缺少必填字段缺 video_url,或带了 notify_url 却没有 client_request_id
4004107地址不合法video_url、notify_url 只支持 http / https
4015003认证信息无效Key 错误或已失效
4035204资源访问被拒绝产品未开通,或 Key 被禁用
429—触发限流降低并发后重试

字段错误示例:

json
{
  "success": false,
  "error": {
    "code": 1001,
    "message": "包含不支持的字段: cues.speaker",
    "details": [{ "field": "cues.speaker" }]
  }
}
json
{
  "success": false,
  "error": {
    "code": 1001,
    "message": "font_size 只支持 small、medium、large",
    "details": [{ "field": "style" }]
  }
}

单价见首页透明接口定价。成功、失败、超时是否计费,以该价格页为准。

  1. 确认 Key 已开通字幕压制。
  2. 用上面的 curl 提交,确认返回 accepted,并记下 meta.request_id。
  3. 轮询查询接口,直到 data.status 为 succeeded,打开 out_data 的第一个地址看成品。
  4. 把 notify_url 换成自己的测试地址,核对回调正文与查询结果一致。
  5. 正式环境发布后再切正式根地址。字段和行为与测试一致。

测试素材:

text
https://media.w3.org/2010/05/sintel/trailer.mp4

预期返回 accepted,约 1–3 分钟出片,成品为烧入字幕的 MP4。