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

# vetta media

> Generate images and video from the terminal, search the generation models and the stock photo library, cut a long video into short clips, transcribe a recording, turn text into speech, and answer a spoken turn with one.

`vetta media generate` renders: an image comes back at once as [files](/docs/cli/files); a video is a **media job** you read back with `vetta media show`. `vetta media models` is how you learn a legal `--model`, for `generate` or to pin with [`vetta agent tools`](/docs/cli/agents#tools).

`vetta media clip <url>` turns a long video into short, scored, captioned clips as a job you poll with `vetta media clip show`. `vetta media models` is how you learn a legal `--model` to pin with [`vetta agent tools`](/docs/cli/agents#tools), and what a session's `generate_image` / `generate_video` will accept. `vetta media stock` searches the [stock photo library](/docs/api/images) for a licensed photo, free. `vetta media transcribe`, `vetta media speak` and `vetta media converse` are the three [audio](/docs/api/audio) routes from the terminal.

There is **no fixed list** of models. The catalogue is read from the provider on every call, so a model published today is callable today — and a model that never existed can never be offered.

## Commands

| Command                                                      | Description                                                          |
| ------------------------------------------------------------ | -------------------------------------------------------------------- |
| `vetta media generate --kind <image\|video> --prompt <text>` | Render an image (synchronous) or queue a video.                      |
| `vetta media show <id>`                                      | One media job.                                                       |
| `vetta media list`                                           | Media jobs, newest first.                                            |
| `vetta media models --kind <image\|video\|stt\|tts\|s2s>`    | Search the models this deploy can render, transcribe or speak with.  |
| `vetta media stock "<query>"`                                | Search the stock photo library. Free; the call is booked at `$0`.    |
| `vetta media clip <url>`                                     | Submit a video-clipping job; prints the queued `media_job`.          |
| `vetta media clip show <id>`                                 | Read a clipping job back, with its clips once completed.             |
| `vetta media clips`                                          | List clipping jobs, newest first.                                    |
| `vetta media transcribe <file\|url>`                         | Transcribe a local file, a stored `fil_` or a public URL.            |
| `vetta media transcription <id>`                             | Re-read a transcription job.                                         |
| `vetta media speak "<text>"`                                 | Turn text into a stored audio file.                                  |
| `vetta media converse <file\|url>`                           | Answer a recorded spoken turn with a spoken reply, stored as a file. |

## generate

```bash theme={"system"}
vetta media generate --kind image --prompt "a paper kite over a grey harbour" --n 2 --aspect-ratio 16:9
```

```json theme={"system"}
{
  "object": "image_generation",
  "model": "example/sketch",
  "files": [
    { "id": "fil_01J...", "object": "file", "name": "image-fil_01J....png", "content_type": "image/png", "size_bytes": 184233, "scope": "published", "session_id": null, "sha256": "…", "created_at": "2026-09-06T12:00:00.000Z" },
    { "id": "fil_01J...", "object": "file", "name": "image-fil_01J....png", "content_type": "image/png", "size_bytes": 179910, "scope": "published", "session_id": null, "sha256": "…", "created_at": "2026-09-06T12:00:00.000Z" }
  ],
  "cost_micro_usd": 60000
}
```

```bash theme={"system"}
vetta media generate --kind video --model example/reel --prompt "waves at dusk" --seconds 4
```

A video answers with the job in `queued`; `vetta media show` it until it is `completed`, then `vetta file download` the `result.files[0].file_id`. Or add `--wait` and the command polls for you, printing the finished job and exiting `0` on `completed`, `1` on `failed`:

```bash theme={"system"}
vetta media generate --kind video --model example/reel --prompt "waves at dusk" --wait \
  | jq -r '.result.files[0].file_id' | xargs vetta file download
```

| Flag             | Description                                                                                                                                          |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--kind`         | **Required.** `image` or `video`.                                                                                                                    |
| `--prompt`       | **Required.** What to render.                                                                                                                        |
| `--model`        | A model id from `vetta media models`. Optional for images (the cheapest is picked); **required** for video, which publishes no price to pick by.     |
| `--image-url`    | A public `http(s)` image to edit, restyle or animate from. Repeat for several (images only).                                                         |
| `--n`            | Images only: how many, 1–4. Each is its own file.                                                                                                    |
| `--seconds`      | Video only: target duration, 1–60.                                                                                                                   |
| `--wait`         | Video only: poll every 2 seconds until the job is `completed` or `failed` (at most the job's own 30-minute deadline). Exit code follows the outcome. |
| `--aspect-ratio` | Such as `16:9` or `9:16`.                                                                                                                            |
| `--seed`         | Repeat an earlier result.                                                                                                                            |

The CLI sends the required `Idempotency-Key` for you; re-running the same command renders again.

## show

```bash theme={"system"}
vetta media show med_01J...
```

```json theme={"system"}
{
  "id": "med_01J...",
  "object": "media_job",
  "kind": "video",
  "status": "completed",
  "model": "example/reel",
  "input": { "model": "example/reel", "prompt": "waves at dusk", "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"
}
```

A failed job carries `error: { code, message }` and `cost_micro_usd: 0` — a job that fails is not billed.

## list

```bash theme={"system"}
vetta media list --kind video --status processing
```

| Flag        | Description                                                                                   |
| ----------- | --------------------------------------------------------------------------------------------- |
| `--kind`    | `video` or `transcription`. Clipping jobs have their own list, [`vetta media clips`](#clips). |
| `--status`  | `queued`, `processing`, `completed` or `failed`.                                              |
| `--session` | Jobs one session's agent submitted. Jobs from the API or CLI have `session_id: null`.         |
| `--limit`   | Page size, 1–100.                                                                             |
| `--after`   | The `next_cursor` of the previous page.                                                       |

## models

```bash theme={"system"}
vetta media models --kind video --search seedance
```

```json theme={"system"}
{
  "object": "list",
  "data": [
    {
      "object": "media_model",
      "id": "bytedance/seedance-2.5",
      "name": "Seedance 2.5",
      "kind": "video",
      "description": "A text- and image-to-video model for short cinematic clips."
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

| Flag       | Description                                                                                                                                  |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--kind`   | **Required.** `image`, `video`, `stt`, `tts` or `s2s`. Each is its own capability with its own catalogue, so there is nothing to default to. |
| `--search` | Matches a model's id, name or description.                                                                                                   |
| `--limit`  | Page size, 1–100.                                                                                                                            |
| `--after`  | The `next_cursor` of the previous page.                                                                                                      |

Images come back cheapest-first, which is the order `generate` and `generate_image` pick their default from. Video models carry no published per-output price, so both ask you to name one rather than guessing.

No price is on the reply. A generation is billed [what it actually cost](/docs/platform/pricing#media-generation--per-finished-job-media-component) once it finishes — nothing is held or checked beforehand, from the CLI, the API or a session; the debit lands once, when the render does.

`--kind stt`, `--kind tts` and `--kind s2s` list the [audio models](/docs/api/audio#the-catalogues) the same way: the managed alias for that direction first, then pinned models cheapest-first where a price is published.

## stock

```bash theme={"system"}
vetta media stock "office workspace" --count 3 --orientation landscape
```

```json theme={"system"}
{
  "data": [
    {
      "object": "stock_photo",
      "id": "2014422",
      "width": 3024,
      "height": 2016,
      "url": "https://images.example/2014422.jpeg?w=940",
      "preview_url": "https://images.example/2014422.jpeg?w=280",
      "alt": "Modern office workspace with laptop",
      "photographer": "Joey Farina",
      "attribution_url": "https://photos.example/photo/2014422/",
      "dominant_color": "#978E82"
    }
  ]
}
```

| Flag            | Description                                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `--count`       | How many photos, 1–30. Default 10. No cursor: `--count` is the whole page.                                                            |
| `--orientation` | `landscape`, `portrait` or `square`.                                                                                                  |
| `--color`       | A dominant colour — a name such as `brown`, or a hex value such as `#978E82`.                                                         |
| `--size`        | Which size `url` points at: `small`, `medium` or `large`. Default `large`. Picks the rendition only — it does not narrow the results. |

Show `photographer`, linked to `attribution_url`, wherever you use the photo — that credit is what the licence asks for. To keep the bytes as a `fil_`, import `url` through [`vetta file`](/docs/cli/files). A deploy with no stock photo library configured answers `feature_not_configured`.

## clip

```bash theme={"system"}
vetta media clip https://cdn.example.com/keynote.mp4 --captions bold --language en --max-seconds 45
```

```json theme={"system"}
{
  "id": "med_01H9HH...",
  "object": "media_job",
  "kind": "clip",
  "status": "queued",
  "model": null,
  "input": { "video_url": "https://cdn.example.com/keynote.mp4", "aspect_ratio": "9:16", "remove_silence": false, "caption_preset": "bold", "language": "en", "min_seconds": 15, "max_seconds": 45, "title": null },
  "result": null,
  "error": null,
  "cost_micro_usd": null,
  "session_id": null,
  "created_at": "2026-09-06T18:00:00.000Z",
  "completed_at": null
}
```

| Flag               | Description                                               |
| ------------------ | --------------------------------------------------------- |
| `--aspect`         | `9:16` (default, reframed to the speaker) or `16:9`.      |
| `--captions`       | `none` (default), `clean`, `bold` or `karaoke`.           |
| `--language`       | BCP-47 hint for transcription, e.g. `de`. Omit to detect. |
| `--min-seconds`    | Shortest clip to keep, 5–180 (default 15).                |
| `--max-seconds`    | Longest clip to keep, 5–180 (default 60).                 |
| `--remove-silence` | Tighten pauses inside each clip.                          |
| `--title`          | A title for clips the scorer does not name itself.        |

The URL must be public `http(s)`; a private or loopback host is refused. The job is billed [what it actually cost](/docs/platform/pricing#media-generation--per-finished-job-media-component) once it finishes, and a submit is refused when the organization's balance is empty.

## clip show

```bash theme={"system"}
vetta media clip show med_01H9HH...
```

The same object, moved on. Once `status` is `completed`, `result.clips` lists each clip's `file_id`, `title`, `start_seconds`, `end_seconds`, `duration_seconds` and `virality` scores (0–100), and `cost_micro_usd` is settled. Fetch a clip's bytes with [`vetta file`](/docs/cli/files).

```bash theme={"system"}
vetta media clip show med_01H9HH... | jq -r '.result.clips[] | "\(.virality.total)\t\(.title)\t\(.file_id)"'
```

## clips

```bash theme={"system"}
vetta media clips --status completed --limit 20
```

| Flag       | Description                                      |
| ---------- | ------------------------------------------------ |
| `--status` | `queued`, `processing`, `completed` or `failed`. |
| `--limit`  | Page size, 1–100.                                |
| `--after`  | The `next_cursor` of the previous page.          |

Only jobs submitted with `vetta media clip` or the API are listed; what an agent's `clip_video` tool cuts inside a session lands in that session as files.

## transcribe

```bash theme={"system"}
vetta media transcribe ./earnings-call.mp3 --language en
vetta media transcribe https://cdn.example.com/earnings-call.mp3
vetta media transcribe fil_01j9x3c2g8h4k5m6n7p8q9r0s1
```

A local path is uploaded first as a published [file](/docs/cli/files), then transcribed; an `http(s)` URL or a `fil_` id is sent as-is. Prints the [transcription job](/docs/api/audio#the-transcription-job) — usually already `completed` with `result.text` and `result.segments`; a long recording the provider queues prints `processing`, to be re-read with `vetta media transcription`.

| Flag              | Description                                                                          |
| ----------------- | ------------------------------------------------------------------------------------ |
| `--model`         | A model from `vetta media models --kind stt`. Omitted, the managed `stt/auto` alias. |
| `--language`      | ISO 639-1 hint, e.g. `en`. Omitted, the model detects it.                            |
| `--no-timestamps` | Skip per-segment timestamps.                                                         |

## transcription

```bash theme={"system"}
vetta media transcription med_01j9x3c2g8h4k5m6n7p8q9r0s1
```

The same job, by id.

## speak

```bash theme={"system"}
vetta media speak "Your order has shipped and arrives Thursday." --voice af_heart --format mp3
```

Prints the speech generation: `model`, `cost_micro_usd`, and the stored `file`. The bytes are one [`vetta file download`](/docs/cli/files) away:

```bash theme={"system"}
vetta media speak "Hello." | jq -r .file.id | xargs vetta file download > hello.mp3
```

| Flag       | Description                                                                          |
| ---------- | ------------------------------------------------------------------------------------ |
| `--model`  | A model from `vetta media models --kind tts`. Omitted, the managed `tts/auto` alias. |
| `--voice`  | One of the model's voices. Omitted, the model's default.                             |
| `--format` | `mp3` (default), `wav` or `ogg`.                                                     |
| `--speed`  | 0.5–2. Omitted, the model's own pace.                                                |

## converse

```bash theme={"system"}
vetta media converse ./question.wav --format wav
vetta media converse https://cdn.example.com/question.wav
vetta media converse fil_01j9x3f0a1b2c3d4e5f6g7h8j9 --voice sage
```

One spoken turn in, the spoken reply out. A local path is uploaded and a public URL is [imported](/docs/cli/files) into the library first — the [route](/docs/api/audio#converse) takes a stored `fil_` only; a `fil_` id is sent as-is. Prints the same speech generation `speak` does:

```bash theme={"system"}
vetta media converse ./question.wav | jq -r .file.id | xargs vetta file download > reply.mp3
```

| Flag       | Description                                                                          |
| ---------- | ------------------------------------------------------------------------------------ |
| `--model`  | A model from `vetta media models --kind s2s`. Omitted, the managed `s2s/auto` alias. |
| `--voice`  | One of the model's voices. Omitted, the model's default.                             |
| `--format` | `mp3` (default), `wav` or `ogg` — the reply's format.                                |

## Pinning a model on an agent

```bash theme={"system"}
vetta media models --kind video --search seedance --limit 1 | jq -r '.data[0].id'
```

Feed that id to `vetta agent tools`:

```bash theme={"system"}
vetta agent tools Refunder --tool generate_video --model bytedance/seedance-2.5
```