> ## 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, generate a sound effect, and answer a spoken turn with one.

`vetta media generate` renders: an image comes back at once as [files](https://vetta.sh/docs/cli/files.md); a video is a **media job** you read back with `vetta media show`. A recurring on-screen persona is a [character](https://vetta.sh/docs/cli/character.md), trained once and rendered as with `--character`. `vetta media models` is how you learn a legal `--model`, for `generate` or to pin with [`vetta agent tools`](https://vetta.sh/docs/cli/agents#tools).

`vetta media edit` submits a Mira edit (`POST /v1/media/edits`) and `vetta media edit` with `--wait` follows `GET /v1/media/edits/{id}`. `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`](https://vetta.sh/docs/cli/agents#tools), and what a session's `generate_image` / `generate_video` will accept. `vetta media stock` searches the [stock photo library](https://vetta.sh/docs/api/images.md) for a licensed photo, free. `vetta media transcribe`, `vetta media speak`, `vetta media sound-effect`, `vetta media music` and `vetta media converse` are the [audio](https://vetta.sh/docs/api/audio.md) 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 mesh [prompt] --image <fil_\|url>...` | Queue a 3D model from a description or 1–4 photos. |
| `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 skills build <url…>` | Build an org skill from 1–3 public reel links; prints the queued build. |
| `vetta media skills revise <id> --feedback <text>` | Run the next round of a build. |
| `vetta media skills get <id>` | Read a build back; reading moves it forward. |
| `vetta media skills list` | List builds, 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 edit "<prompt>" --video <fil_\|url>` | Submit a Mira edit (`POST /v1/media/edits`). `--wait` follows `GET /v1/media/edits/{id}`. |
| `vetta media sound-effect "<prompt>"` | Generate a sound effect from a description, stored as a file. |
| `vetta media music "<prompt>"` | Generate an original song from a description, stored as a 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: an image gets the platform's default image model, a video the first of the platform's video defaults the catalogue publishes — `black-forest-labs/flux-3-max`, `minimax/hailuo-3`, `bytedance/seedance-2.5`, then `alibaba/wan-3.0/text-to-video`. |
| `--image-url` | An image to edit, restyle or animate from — a stored `fil_` id or a public `http(s)` URL. Repeat for several (images only, up to 4). |
| `--character` | Render as a `ready` [character](https://vetta.sh/docs/cli/character.md), by `chr_` id or name. On an image it is the reference (not combined with `--image-url`); on `--kind video` it needs `--image-url <fil_>` of a still rendered as that character, which becomes the first frame. |
| `--style` | Images only: draw the image in a named look (`Library`, `Phone snap`, `Quiet luxury`, …; a character's usual looks are its `style_pack`). |
| `--character-strength` | Images only, with `--character`: 0.5 to 1, how strictly the face is held (try `0.85` for close-ups). Leave it out otherwise. |
| `--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.

## mesh

A textured GLB from a description or from one to four photos of the same object — a [media job](https://vetta.sh/docs/api/meshes.md) like a video. From a description it can also be rigged with an idle animation. For a part with real dimensions, build it instead: [`vetta computer build-3d`](https://vetta.sh/docs/cli/computer#build-3d).

```bash theme={"system"}
vetta media mesh "a weathered bronze lantern" --wait --out lantern.glb
vetta media mesh --image fil_01J... --image fil_01K... --no-texture
```

| Flag | Description |
| - | - |
| `[prompt]` | What to model. Give this or `--image`, not both. |
| `--image` | A photo of the object, a stored `fil_` id or a public `https` URL. Repeat for up to 4 views of the same object. |
| `--no-texture` | Geometry only, untextured; cheaper. |
| `--rig` | A description only: rig the model and give it an idle animation. |
| `--model` | A model id from `GET /v1/media/models?kind=mesh`. Optional: a description and photos each have a default. |
| `--wait` | Poll until the job is `completed` or `failed`, print it, and exit `0` or `1`. A model from a description takes several minutes. |
| `--out` | With `--wait`: save the finished GLB to this path. |

Each job is priced for the exact options it used, and only when it completes; a failed job is free. See [3D assets](https://vetta.sh/docs/capabilities/3d.md#pricing).

## 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`, `mesh` 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. |

Models come back in the order `generate` and `generate_image` pick their default from: the platform's own first, then cheapest-first where a price is published. A video defaults to the first of the platform's video defaults the catalogue publishes — `black-forest-labs/flux-3-max`, `minimax/hailuo-3`, `bytedance/seedance-2.5`, then `alibaba/wan-3.0/text-to-video`; if the catalogue publishes none of them, you are asked to name one.

No price is on the reply. A generation is billed [what it cost](https://vetta.sh/docs/platform/pricing.md#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. Training a [character](https://vetta.sh/docs/cli/character.md) is the exception: the balance must cover it first.

`--kind stt`, `--kind tts` and `--kind s2s` list the [audio models](https://vetta.sh/docs/api/audio.md#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`](https://vetta.sh/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](https://vetta.sh/docs/platform/pricing.md#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`](https://vetta.sh/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.

## skills

```bash theme={"system"}
vetta media skills build https://www.instagram.com/reel/C1abc/ https://www.instagram.com/reel/C2def/ --name "Slow feast" --wait
vetta media skills revise ctp_01H9HH... --feedback "Slower cuts, warmer color grade" --wait
vetta media skills get ctp_01H9HH...
vetta media skills list --state ready
```

`build` takes one to three public reel links and queues a [skill build](https://vetta.sh/docs/api/media-skills.md); every round that comes back `ready` is saved as the next version of one org skill. `revise` runs the next round from your feedback. `get` reads a build and moves it forward; `list` does not. With `--wait`, the command follows the newest round until it is `ready` and prints the build with `skill_ref` (`slug@version`), or exits 1 when the round fails.

| Flag | Description |
| - | - |
| `--name` | `build`: a name for the skill (up to 80 characters). |
| `--description` | `build`: what the skill is for (up to 2000 characters). |
| `--feedback` | `revise`: what to change (required). |
| `--wait` | `build`, `revise`: poll until the round is `ready` or `failed`. |
| `--state` | `list`: `setup`, `building` or `ready`. |
| `--limit` | `list`: page size, 1–100. |
| `--after` | `list`: the `next_cursor` of the previous page. |

## 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](https://vetta.sh/docs/cli/files.md), then transcribed; an `http(s)` URL or a `fil_` id is sent as-is. Prints the [transcription job](https://vetta.sh/docs/api/audio.md#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`](https://vetta.sh/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. |

## edit

```bash theme={"system"}
vetta media edit "the same people, on a rooftop at dusk" --video fil_01J... --mode scene
vetta media edit "swap the person for the one in the photo" --video fil_01J... --reference fil_01K... --mode person_swap --wait
```

`POST /v1/media/edits`. `--video` is a library video or a public URL. `--reference` repeats, up to four pictures. `--mode` is `scene`, `outfit_or_object` or `person_swap`. `--wait` polls `GET /v1/media/edits/{id}` until the edit finishes.

## sound-effect

```bash theme={"system"}
vetta media sound-effect "a heavy wooden door slamming shut, echoing" --seconds 3
```

Generates a short clip from a description — ambience, foley, a sting — and prints the sound generation: the stored `file`, its `duration_seconds` and `cost_micro_usd`. Add `--loop` for seamless ambience. The bytes are one [`vetta file download`](https://vetta.sh/docs/cli/files) away:

```bash theme={"system"}
vetta media sound-effect "rain on a tin roof" | jq -r .file.id | xargs vetta file download > rain.mp3
```

| Flag | Description |
| - | - |
| `--seconds` | Clip length in seconds, 0.5–30; decimals allowed. Omitted, the generator fits the length to the prompt. |
| `--loop` | Make the clip loop seamlessly — for ambience and backgrounds. |

## music

```bash theme={"system"}
vetta media music "an upbeat synthwave track with driving bass and bright arpeggios" --seconds 30
```

Generates an original song from a description — any genre, mood or instrumentation — and prints the music generation: the stored `file`, its `duration_seconds` and `cost_micro_usd`. Add `--instrumental` for a track with no vocals. The bytes are one [`vetta file download`](https://vetta.sh/docs/cli/files) away:

```bash theme={"system"}
vetta media music "a mellow lo-fi beat to study to" | jq -r .file.id | xargs vetta file download > beat.mp3
```

| Flag | Description |
| - | - |
| `--seconds` | Song length in seconds, 3–300; decimals allowed. Omitted, 30. |
| `--instrumental` | Force an instrumental track with no vocals. |

## 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](https://vetta.sh/docs/cli/files.md) into the library first — the [route](https://vetta.sh/docs/api/audio.md#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 agt_01j8rf6tq2m4vz9xkp3n7c5hwd --tool generate_video --model bytedance/seedance-2.5
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.