Video jobs
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.
Lifecycle
Section titled “Lifecycle” 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.
One video at a time
Section titled “One video at a time”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.
Polling
Section titled “Polling”- 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
Section titled “Progress”"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 fields
Section titled “Cost fields”"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.
Result and download links
Section titled “Result and download links”When status is completed:
"result": { "video_url": "https://...", "poster_url": "https://...", "expires_in_sec": 86400}video_urlis a signed download link to the video file. It expires afterexpires_in_secseconds. CallGET /v1/videos/{id}again for a fresh link; do not store the link itself.poster_urlis a still image for the video, ornull.- The video is also in the account’s library in Clipbeat Studio (
studio_url), where the owner can edit it or reshoot scenes.
The video object
Section titled “The video object”{ "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. |
Start parameters
Section titled “Start parameters”| 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.
Listing videos
Section titled “Listing videos”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.