# Video jobs

> The life of a Clipbeat video from start to download, its statuses, progress, cost fields and the video object.

Source: https://docs.clipbeat.app/concepts/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

```text
                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

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

- Poll every **30 to 60 seconds**. Faster polling does not make the video faster and uses your
  [rate limit](https://docs.clipbeat.app/rate-limits/).
- 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

```json
"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

```json
"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](https://docs.clipbeat.app/pricing/).

## Result and download links

When `status` is `completed`:

```json
"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](https://studio.clipbeat.app) (`studio_url`), where
  the owner can edit it or reshoot scenes.

## The video object

```json
{
  "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](#lifecycle). |
| `tier` | `preview`, `standard`, `plus`, `premium` | See [Tiers](https://docs.clipbeat.app/concepts/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](#progress). |
| `cost` | object | See [Cost fields](#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

| 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](https://docs.clipbeat.app/content-policy/).

## 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.
