FFmpeg Media · FFmpeg

Character NameplateNEW

📌 What is this：Burn 1-4 lower-third nameplates (character name + role subtitle, each with its own time window) into the video. Video is re-encoded, the audio track is stream-copied, and resolution / frame rate / SAR stay identical to the source.

💡 When to use：Use to introduce a character on first appearance. Each nameplate takes an appearance time (startMs) and a display length (durationMs); slot controls vertical stacking (0 is lowest). No escaping needed — colons, quotes, percent signs render as-is. Title and subtitle are single-line, <=64 chars each (no auto-wrap). A CJK font is built in, nothing to configure. The output keeps the source spec, so it still joins un-nameplated clips via concat's zero-re-encode fast path.

Endpoints

Usage	Method	Path
Submit task	POST	/v1/ffmpeg/overlay_text
Query Result	GET	/v1/ffmpeg/info?id={taskId}

⏱ Recommended polling interval：Poll every 3-5s (response includes progress 0-100) until status = succeeded / failed. status = queued means the task is enqueued and waiting to start (not charged yet) — just keep polling. Single-task timeout is 300s with auto-refund.

Request Parameters

Param	Type	Required	Description
inputUrl	string	Required	Input media URL on a trusted allowlist domain (platform CDN or a trusted-source CDN); upload first to obtain one, or use an asset URL already on a trusted CDN
overlays	object[]	Required	Nameplate array, 1-4 items; each { style: style name (currently only nameplate), startMs: appearance time in ms (>=0), durationMs: display length in ms (>0), slot: vertical slot 0-3 (default 0, no duplicates within one request), title: character name (required, single line <=64 chars), subtitle: role subtitle (optional, single line <=64 chars) }. A window past the video end is clamped to the tail; an item starting after the end is silently dropped
webhookUrl	string	—	Completion webhook URL (optional)

Request Example

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>" }

Response Example

{
  "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
  }
}

Billing & Credits

Factor 1.0; 1 min 720P ~ 3 credits (billed by video length; the number of nameplates does not change the price) (x your user rate). Auto-refunded on failure.