字幕压制接口文档
把字幕文本烧进视频画面,输出新的 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 | 待发布。接口和字段与测试一致 |
路径接在根地址后面。例如测试环境提交压制:
POST https://test-star-api.aiaibase.com/api/subtitle_render健康检查:GET {根地址}/public/health,返回 HTTP 200 即可用。
请求体为 JSON,Content-Type: application/json。单次请求体不超过 1 MB。认证只使用请求头:
Authorization: Bearer {API Key}{API Key} 由星鉴开通,开通时会同时开通字幕压制的产品权限。Key 只能放在服务端。
需要从音轨识别字幕时,使用音频字幕。需要自动选择字幕轨、画面字幕或语音识别时,使用智能字幕。只翻译已经分好条的字幕时,使用字幕翻译。本接口只负责把已有字幕烧进画面。
所有响应都是同一结构。
| 字段 | 类型 | 说明 |
|---|---|---|
success | bool | 受理成功、处理中、处理成功为 true;失败为 false |
data | object | 成功或处理中的业务数据 |
message | string | 失败说明 |
error | object | 失败时的错误。含 code、message,参数错误时还有 details |
meta.request_id | string | 平台任务号。查询任务用这个值 |
meta.timestamp | string | 响应时间,例如 2026-11-03T08:20:36Z |
{
"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 | 否 | string | small、medium、large,默认 medium |
style.font | 否 | string | sans、serif,默认 sans |
cover | 否 | object 或 string | 封面遮挡。可传对象,也可传 JSON 字符串 |
cover.mode | 否 | string | none、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 就是后续查询用的任务号。
{
"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"
}
}请求示例
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 这一档。
处理中:
{
"success": true,
"data": {
"status": "accepted",
"client_request_id": "order-20261103-0001"
}
}成功:
{
"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 个。链接由上游存储提供,拿到后尽快转存。
失败:
{
"success": false,
"message": "上游处理失败",
"error": { "code": 3600, "message": "上游处理失败" }
}提交时传了 notify_url,任务进入终态后星鉴会 POST 到该地址。请求体与查询任务的响应相同。回调丢失时,仍用查询接口兜底。
| 项 | 值 |
|---|---|
| 方法 | POST |
Content-Type | application/json |
User-Agent | star-openapi |
| 请求体 | 与 GET /api/tasks/{request_id} 的响应 JSON 相同 |
| 成功条件 | 回调地址返回 HTTP 2xx |
| 重试 | 非 2xx 视为失败,间隔 30 秒,最多 4 次 |
回调可能重复投递。用 meta.request_id 或 client_request_id 做幂等。
| HTTP | 业务码 | 说明 | 处理 |
|---|---|---|---|
| 400 | 1001 | 字段不支持或参数非法 | 看 error.details[].field |
| 413 | 1004 | 请求实体过大 | 请求体不超过 1 MB,cues 不超过 3000 条 |
| 400 | 1101 | JSON 格式错误 | 检查请求体 |
| 401 | 1102 | 缺少请求头 | 加 Authorization |
| 503 | 1502 | 服务暂不可用 | 稍后重试 |
| 502 | 3600 | 上游处理失败 | 可重试。换 client_request_id,或排障后重提 |
| 409 | 4003 | 同一调用方请求号,请求体不同 | 换请求号,或把请求体改回第一次 |
| 400 | 4102 | 缺少必填字段 | 缺 video_url,或带了 notify_url 却没有 client_request_id |
| 400 | 4107 | 地址不合法 | video_url、notify_url 只支持 http / https |
| 401 | 5003 | 认证信息无效 | Key 错误或已失效 |
| 403 | 5204 | 资源访问被拒绝 | 产品未开通,或 Key 被禁用 |
| 429 | — | 触发限流 | 降低并发后重试 |
字段错误示例:
{
"success": false,
"error": {
"code": 1001,
"message": "包含不支持的字段: cues.speaker",
"details": [{ "field": "cues.speaker" }]
}
}{
"success": false,
"error": {
"code": 1001,
"message": "font_size 只支持 small、medium、large",
"details": [{ "field": "style" }]
}
}单价见首页透明接口定价。成功、失败、超时是否计费,以该价格页为准。
- 确认 Key 已开通字幕压制。
- 用上面的 curl 提交,确认返回
accepted,并记下meta.request_id。 - 轮询查询接口,直到
data.status为succeeded,打开out_data的第一个地址看成品。 - 把
notify_url换成自己的测试地址,核对回调正文与查询结果一致。 - 正式环境发布后再切正式根地址。字段和行为与测试一致。
测试素材:
https://media.w3.org/2010/05/sintel/trailer.mp4预期返回 accepted,约 1–3 分钟出片,成品为烧入字幕的 MP4。