> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Video
> Generate video over REST — a queued job you read back, with the finished file on it.
A video renders for minutes, so `POST /v1/media/videos` does not wait: it answers `202` with a **media job** in `queued`, and you read the job back until it is `completed` or `failed`. The finished clip is a [file](/docs/api/files). Images are the synchronous case — see [Images](/docs/api/images).
## The media job object
`med_…`.
Always `media_job`.
`video`. Other async media kinds share the object and the routes below.
`queued` → `processing` → `completed` | `failed`.
The model rendering it.
The request as accepted.
On `completed`: `{ files: [{ file_id, content_type, width, height, duration_seconds }] }`. Dimensions are `null` where the model did not report them.
On `failed`: `{ code, message }` — the reason, safe to repeat, so a refusal and an outage read differently.
What was debited, in integer micro-USD, once the job finished: `null` while it runs, `0` on a failure — a job that fails is not billed.
The session whose agent submitted it; `null` for a job submitted through this API.
Submission time.
When it reached a terminal status.
## Generate a video
`POST /v1/media/videos` → `202 Accepted` — scope `agents:write`, [`Idempotency-Key`](/docs/api/overview#idempotency) **required**.
A model id from [`GET /v1/media/models?kind=video`](/docs/api/media#search-models). Video models publish no price, so there is no default to pick for you.
What to render.
One public `http(s)` image to animate from. A private or loopback host is `validation_failed`.
Target duration, 1–60. Models honour it as they can.
Such as `16:9` or `9:16`.
Repeat an earlier result.
```bash cURL theme={"system"}
curl -fsSL https://api.vetta.sh/v1/media/videos \
-H "authorization: Bearer sk_live_..." \
-H "idempotency-key: $(uuidgen)" \
-H "content-type: application/json" \
-d '{ "model": "example/reel", "prompt": "waves at dusk, slow pan", "seconds": 4 }'
```
```ts SDK theme={"system"}
let job = await client.media.videos.generate({ model: "example/reel", prompt: "waves at dusk", seconds: 4 });
while (job.status === "queued" || job.status === "processing") {
await new Promise((r) => setTimeout(r, 5_000));
job = await client.media.get(job.id);
}
```
```bash CLI theme={"system"}
vetta media generate --kind video --model example/reel --prompt "waves at dusk" --seconds 4
vetta media show med_01J...
```
```json 202 Accepted theme={"system"}
{
"id": "med_01J...",
"object": "media_job",
"kind": "video",
"status": "queued",
"model": "example/reel",
"input": { "model": "example/reel", "prompt": "waves at dusk, slow pan", "seconds": 4 },
"result": null,
"error": null,
"cost_micro_usd": null,
"session_id": null,
"created_at": "2026-09-06T12:00:00.000Z",
"completed_at": null
}
```
## Retrieve a job
`GET /v1/media/{id}` → `200 OK` — scope `agents:read`. Poll it; a job left rendering for over thirty minutes is failed and not billed. Any `med_` reads here, a [clip job](/docs/api/clips) included — the same object `GET /v1/media/clips/{id}` answers.
```json Response theme={"system"}
{
"id": "med_01J...",
"object": "media_job",
"kind": "video",
"status": "completed",
"model": "example/reel",
"input": { "model": "example/reel", "prompt": "waves at dusk, slow pan", "seconds": 4 },
"result": {
"files": [
{ "file_id": "fil_01J...", "content_type": "video/mp4", "width": null, "height": null, "duration_seconds": null }
]
},
"error": null,
"cost_micro_usd": 412000,
"session_id": null,
"created_at": "2026-09-06T12:00:00.000Z",
"completed_at": "2026-09-06T12:03:41.000Z"
}
```
Read the clip with [`GET /v1/files/{file_id}?download=true`](/docs/api/files#retrieve-a-file). The file carries `source.type = video_generation` and `source.job_id` = this job.
A job an agent submitted with `generate_video` carries its `session_id`, and that session's [event stream](/docs/api/events#event-types) announces it: `media.job.queued`, then `media.job.completed` or `media.job.failed`. A job submitted here has no session, so poll it.
## List jobs
`GET /v1/media` → `200 OK`, cursor-paginated — scope `agents:read`. See [Pagination](/docs/api/pagination).
`video` (or another async kind).
`queued`, `processing`, `completed` or `failed`.
Jobs an agent submitted from one session.
Page size, 1–100.
The `next_cursor` of the previous page.
## Billing
A job is billed **what it actually cost**, on the media tier, when it completes; nothing is quoted beforehand. At submit the organization's prepaid balance is checked against a small floor — `insufficient_credits` if it is below it — and the debit settles under the job id at completion, exactly once. A job that fails, is refused, or is abandoned is not billed.
## Errors
| Code | When |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| `validation_failed` | Missing `Idempotency-Key`, an unknown `model`, a private-host `image_urls` entry, `seconds` outside 1–60. |
| `insufficient_credits` | The prepaid balance is below the admission floor. |
| `provider_error` | The model would not take the job. Nothing is queued or billed. |
| `not_found` | No such `med_` in this organization. |
| `feature_not_configured` | This deploy has no generation provider or no persistence configured. |