vetta media

vetta media generate renders: an image comes back at once as 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. 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, and what a session’s generate_image / generate_video will accept. vetta media stock searches the stock photo library for a licensed photo, free. vetta media transcribe, vetta media speak and vetta media converse are the three 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

vetta media generate --kind image --prompt "a paper kite over a grey harbour" --n 2 --aspect-ratio 16:9

{
  "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
}

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:

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

vetta media show med_01J...

{
  "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

vetta media list --kind video --status processing

Flag	Description
`--kind`	`video` or `transcription`. Clipping jobs have their own list, `vetta media 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

vetta media models --kind video --search seedance

{
  "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 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 the same way: the managed alias for that direction first, then pinned models cheapest-first where a price is published.

stock

vetta media stock "office workspace" --count 3 --orientation landscape

{
  "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. A deploy with no stock photo library configured answers feature_not_configured.

clip

vetta media clip https://cdn.example.com/keynote.mp4 --captions bold --language en --max-seconds 45

{
  "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 once it finishes, and a submit is refused when the organization’s balance is empty.

clip show

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.

vetta media clip show med_01H9HH... | jq -r '.result.clips[] | "\(.virality.total)\t\(.title)\t\(.file_id)"'

clips

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

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, then transcribed; an http(s) URL or a fil_ id is sent as-is. Prints 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

vetta media transcription med_01j9x3c2g8h4k5m6n7p8q9r0s1

The same job, by id.

speak

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 away:

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

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 into the library first — the route takes a stored fil_ only; a fil_ id is sent as-is. Prints the same speech generation speak does:

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

vetta media models --kind video --search seedance --limit 1 | jq -r '.data[0].id'

Feed that id to vetta agent tools:

vetta agent tools Refunder --tool generate_video --model bytedance/seedance-2.5

Getting started

Building & running

Organization

Identity

Commands

generate

show

list

models

stock

clip

clip show

clips

transcribe

transcription

speak

converse

Pinning a model on an agent

​Commands

​generate

​show

​list

​models

​stock

​clip

​clip show

​clips

​transcribe

​transcription

​speak

​converse

​Pinning a model on an agent

Commands

generate

show

list

models

stock

clip

clip show

clips

transcribe

transcription

speak

converse

Pinning a model on an agent