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; a video is a media job you read back with vetta media show. A recurring on-screen persona is a character, 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.

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, 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, vetta media sound-effect, vetta media music and vetta media converse are the 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 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

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: 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, 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 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.

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.

​

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

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 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 is the exception: the balance must cover it first.

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

​

skills

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; 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

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.

​

edit

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

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

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

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

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

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 agt_01j8rf6tq2m4vz9xkp3n7c5hwd --tool generate_video --model bytedance/seedance-2.5