CQTAI
FFmpeg 媒体处理 · FFmpeg

字幕合成NEW

📌 这是什么：给视频加字幕：soft = 软字幕轨道（可开关、不重编码）；hard = 硬字幕烧进画面（永久显示、必然重编码）。
💡 什么时候用：想给视频配字幕时用。要保留「可开关字幕」选 soft；要字幕永远显示（如短视频/竖屏投稿）选 hard。识别 .srt / .ass / .vtt，其它后缀按 .srt 处理；中文硬字幕已内置 Noto CJK 字体，无需额外指定。

接口地址

用途方法路径
提交任务POST/v1/ffmpeg/burn_subtitle
查询结果GET/v1/ffmpeg/info?id={taskId}
⏱ 建议轮询时间：建议每 3～5 秒轮询一次（响应含 progress 0→100），直到 status = succeeded / failed。status = queued 表示已入队、排队等待执行（尚未扣费），继续轮询即可。单任务超时 300 秒、超时退款。

请求参数

参数类型必填说明
inputUrlstring必填输入媒体 URL，须为受信白名单域名（平台 CDN 或受信来源 CDN）；可先用 upload 上传获取，或直接用已在受信 CDN 上的素材 URL
subtitleUrlstring必填字幕文件 URL（受信白名单域名）；识别 .srt / .ass / .vtt，其它后缀按 .srt 处理
modestring—合成方式：soft（软字幕轨道，mov_text，不重编码，输出 mp4）/ hard（硬字幕烧进画面，视频重编码、音频直拷），默认 soft
webhookUrlstring—完成回调地址（可选）

请求示例

curl -X POST https://api.cqtai.com/v1/ffmpeg/burn_subtitle \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{ "inputUrl": "https://cdn.novapi.ai/veo31/1788164205419_de868f9d69d445baaf577d42e87a236f.mp4", "subtitleUrl": "https://cdn.novapi.ai/tmp/captions.srt", "mode": "hard" }'
# -> { "code":200, "data":"<taskId>" }

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "<taskId>",
    "operation": "transcode",
    "status": "succeeded",
    "progress": 100,
    "resultUrl": "https://cdn.novapi.ai/ffmpeg/xxx.mp4",
    "costPoints": 3,
    "errorMsg": null
  }
}