FFmpeg 媒体处理 · FFmpeg

人物名牌文字NEW

📌 这是什么：把 1~4 条「下三分之一名牌」（角色名 + 身份副标题，各带时间窗）烧进视频画面。视频重编码、音轨原样拷贝，分辨率 / 帧率 / SAR 与源一致。

💡 什么时候用：人物首次出场做登场介绍时用。每条名牌指定出现时刻 startMs 与显示时长 durationMs，slot 控制竖向叠放（0 最靠下）。文字无需自己转义，冒号/引号/百分号等都会原样显示；标题、副标题各限单行 ≤64 字符（不自动折行）。中文字体已内置，无需额外指定。输出与源同规格，可直接与未加名牌的分镜走 concat 的零重编码快通道拼接。

接口地址

用途	方法	路径
提交任务	POST	/v1/ffmpeg/overlay_text
查询结果	GET	/v1/ffmpeg/info?id={taskId}

⏱ 建议轮询时间：建议每 3～5 秒轮询一次（响应含 progress 0→100），直到 status = succeeded / failed。status = queued 表示已入队、排队等待执行（尚未扣费），继续轮询即可。单任务超时 300 秒、超时退款。

请求参数

参数	类型	必填	说明
inputUrl	string	必填	输入媒体 URL，须为受信白名单域名（平台 CDN 或受信来源 CDN）；可先用 upload 上传获取，或直接用已在受信 CDN 上的素材 URL
overlays	object[]	必填	名牌数组，1~4 条；每项 { style: 样式名（当前仅 nameplate）, startMs: 出现时刻(毫秒,≥0), durationMs: 显示时长(毫秒,>0), slot: 竖向槽位 0~3（默认 0，同一请求内不可重复）, title: 角色名（必填，单行 ≤64 字符）, subtitle: 身份副标题（可选，单行 ≤64 字符） }。超出视频时长的时间窗自动裁到片尾；起始时刻已超过时长的该条静默丢弃
webhookUrl	string	—	完成回调地址（可选）

请求示例

curl -X POST https://api.cqtai.com/v1/ffmpeg/overlay_text \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{ "inputUrl": "https://cdn.novapi.ai/veo31/1788164205419_de868f9d69d445baaf577d42e87a236f.mp4", "overlays": [{ "style": "nameplate", "startMs": 400, "durationMs": 2400, "slot": 0, "title": "林晚", "subtitle": "医者" }, { "style": "nameplate", "startMs": 400, "durationMs": 2400, "slot": 1, "title": "陈舟" }] }'
# -> { "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
  }
}