CQTAI
FFmpeg Media · FFmpeg

FFmpeg Media · IntroductionNEW

FFmpeg media processing API: transcode, compress, scale, trim, frame extraction, single-frame grab, watermark, subtitle burn-in, character nameplates, concat, concat with transitions, mux, timeline audio mux, audio extraction, GIF conversion, thumbnail, media probe, deep QC, and file upload. Flow: (1) upload a file to get a CDN URL → (2) call an operation (use that URL as input) → (3) poll by taskId until succeeded / failed. Inputs only accept URLs on a trusted allowlist domain (platform CDN or a trusted-source CDN); if an asset is already on a trusted CDN you can skip upload and use it directly. Billed by credits: charged when the task starts running (the price can only be determined after probing the input), not yet charged while queued, auto-refunded in full on failure; invalid parameters and insufficient balance are rejected before any charge. A busy platform is not an error: when every node is busy, submit still returns a taskId and the task waits as queued, then starts automatically — just keep polling, no need to retry yourself.

How to call

  1. Upload: POST /v1/ffmpeg/upload (multipart), get a CDN URL.
  2. Submit: POST /v1/ffmpeg/{operation}, use that URL as input, returns a taskId.
  3. Query: GET /v1/ffmpeg/info?id=taskId, poll until status = succeeded.

Operations

POSTUpload Fileupload
Upload a media file (multipart); returns a CDN URL synchronously.
POSTMedia Probeprobe
Extract media metadata: duration / resolution / bitrate / codec. Returns instantly.
POSTDeep QCqc
Read-only QC: decodes the finished video twice (one video pass, one audio pass) with detector filters and returns a small JSON report — black-frame, freeze and silence segments plus EBU R128 loudness. It produces no media file and leaves the source untouched.
POSTTranscodetranscode
Convert container format and audio/video codecs.
POSTCompresscompress
Reduce video file size.
POSTScalescale
Scale the video to a target resolution.
POSTTrimtrim
Cut a time segment out of the video.
POSTExtract Audioextract_audio
Extract the audio track from a video.
POSTVideo to GIFto_gif
Convert a video segment to an animated GIF.
POSTThumbnailthumbnail
Capture a single frame at a given time.
POSTWatermarkwatermark
Overlay an image watermark on the video.
POSTBurn Subtitleburn_subtitle
Add subtitles to a video: soft = a switchable subtitle track (no re-encode); hard = burned into the pixels (permanent, forces a re-encode).
POSTCharacter Nameplateoverlay_text
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.
POSTConcatconcat
Join multiple videos into one, in order.
POSTMux Audiomux
Merge audio into video (replace or add a track).
POSTExtract Framesframes
Export image frames by interval or FPS; the output is packaged into a single .zip and resultUrl points to that archive.
POSTExtract Single Frameextract_frame
Extract one frame from a video: the last frame or a given timestamp; output keeps the original resolution without scaling.
POSTTimeline Audio Muxmux_timeline
Place multiple audio clips into a video at their own time offsets — positioning and muxing the whole track in one call.
POSTConcat with Transitionsconcat_transition
Join clips in order with optional crossfade or dip-to-black transitions at chosen seams, plus head fade-in and tail fade-out.

💰 See the pricing page for prices →

Concurrency & Limits

  • Per-account concurrent tasks: limited by your account quota (shared with generation tasks on the site); both queued and running count. Submissions beyond the quota return 429 with your limit in the message (max N)
  • A busy platform is not an error: when every node is busy, submit still returns a taskId and the task waits as queued, then starts automatically — just keep polling, no need to retry
  • Single-task timeout: 300s (refunded on timeout)
  • Upload limit 200MB; task input download limit 1GB
  • Input URLs must be on a trusted allowlist domain (platform CDN + trusted-source CDN)

Common Errors

CodemsgMeaningHow to fix
400invalid params / non-allowlist urlInvalid params or input URL not on allowlist (rejected before charge)Check enum/range; upload input first to get a CDN URL
429Task limit reached (max N)Exceeds your account concurrent-task quota (shared with generation tasks on the site; both queued and running count); the max N in the message is your limitWait for existing tasks to finish, or contact us to raise the quota. Note: a busy platform alone never returns 429 — those tasks simply wait as queued
500failed / timeoutProcessing failed or timed out (300s); credits auto-refunded, see data.errorMsgAdjust input/params per errorMsg and retry