Skip to content

Video jobs

View as Markdown

A video job is one music video being made from one song. You start it with POST /v1/videos (or the MCP tool create_video_from_song_url) and follow it with GET /v1/videos/{id} (or get_video_status). Making a video takes minutes, so the API is asynchronous: starting returns at once with 202 Accepted, the work happens in the background.

POST /v1/videos
│ 202 Accepted, credits reserved
▼
┌──────────┐
│ queued │ waiting for a free slot
└────┬─────┘
▼
┌──────────┐ progress.stage: plan → images → motion → render
│ running │ (polishing: a final quality pass)
└────┬─────┘
┌──────────┼───────────────┐
▼ ▼ ▼
┌───────────┐ ┌────────┐ ┌──────────┐
│ completed │ │ failed │ │ canceled │
└───────────┘ └────────┘ └──────────┘
result.video_url error stopped early
credits charged credits unused credits
(partial refund returned returned
if shots missed)
Status Final Meaning What to do
queued no Accepted and waiting to start. Poll.
running no Being made. progress shows the step. Poll.
completed yes Done. result.video_url has the file. Download or share the link.
failed yes Could not be made. error says why. Reserved credits are returned. Start again, or contact support.
canceled yes Stopped before it finished (for example from Studio). Unused credits are returned. Nothing.

Treat any status you do not recognize as “not final yet” and keep polling.

An account makes one video at a time. Starting another while one is queued or running returns 409 video_in_progress with the current video in video. Wait for it to finish, then start the next one.

  • Poll every 30 to 60 seconds. Faster polling does not make the video faster and uses your rate limit.
  • A preview takes minutes. A full video takes longer, depending on tier and song length.
  • There are no webhooks yet. Polling is the way to know when a video is done.
"progress": { "stage": "motion", "done": 4, "total": 12, "percent": 33 }
Field Description
stage The current step: plan, images, motion, render, polishing or done. For display only; new values can appear.
done, total Units finished out of the total for the current job.
percent done / total as a whole number from 0 to 100.

progress is null until the job has started.

"cost": { "credits_reserved": 280, "credits_charged": 280, "credits_refunded": 0, "usd": 14 }
Field Description
credits_reserved Taken from the balance when the job started.
credits_charged Final charge, set when the job finishes.
credits_refunded Returned to the balance.
usd Reserved amount while the job runs; charged amount once it is completed, failed or canceled.

See Pricing & credits.

When status is completed:

"result": {
"video_url": "https://...",
"poster_url": "https://...",
"expires_in_sec": 86400
}
  • video_url is a signed download link to the video file. It expires after expires_in_sec seconds. Call GET /v1/videos/{id} again for a fresh link; do not store the link itself.
  • poster_url is a still image for the video, or null.
  • The video is also in the account’s library in Clipbeat Studio (studio_url), where the owner can edit it or reshoot scenes.
{
"id": "f1e2d3c4-b5a6-4789-8abc-def012345678",
"status": "running",
"tier": "standard",
"title": "My Song",
"aspect": "16:9",
"created_at": "2026-11-22T09:16:40.000Z",
"progress": { "stage": "images", "done": 3, "total": 12, "percent": 25 },
"cost": { "credits_reserved": 280, "credits_charged": 0, "credits_refunded": 0, "usd": 14 },
"result": null,
"studio_url": "https://studio.clipbeat.app/"
}
Field Type Description
id string (UUID) Video id.
status string See Lifecycle.
tier preview, standard, plus, premium See Tiers.
title string or null Title shown on the video.
aspect 16:9, 9:16 or null Frame shape.
created_at string (ISO 8601) or null When the job was created.
progress object or null See Progress.
cost object See Cost fields.
result object or null Set only when completed.
error string Present only when the job failed.
studio_url string Where the owner can open the video in Clipbeat Studio.
Field Required Description
song_id yes A song of this account in status ready.
tier no preview (default), standard, plus or premium.
style no World, place and look of the video, up to 600 characters.
character no The original AI lead singer, up to 300 characters. No real or famous people.
aspect no 16:9 or 9:16.
title no Up to 120 characters. Defaults to the song title.

style, character and title are checked before the job starts. A brief that names a real person, a celebrity, a protected character or a brand, or asks for unsafe content, is rejected with 422 brief_rejected and nothing is charged. See Content policy.

GET /v1/videos?limit=20 returns the account’s latest videos, newest first, as { "videos": [ ... ] }. limit is 1 to 50, default 20. It includes videos made in Studio, not only through the API.