vetta character

A character is a consistent on-screen persona — an AI influencer, a recurring host — trained once from a handful of reference photos and then pinned into every later image, so the same face carries across a whole channel. Training takes a few minutes: create answers at once with the character in training, and get is what you poll until it is ready. A character is addressed by its chr_ id or its name. API detail: Characters.

Commands

Command	Description
`vetta character create --name <name> --image <ref> --consent`	Train a character. Paid; prints it in `training`.
`vetta character get <id\|name>`	One character, its status advanced from the trainer.
`vetta character list`	Your characters, newest first, then the prebuilt ones (`"prebuilt": true`).
`vetta character delete <id\|name>`	Delete one and free its name.

create

vetta character create --name Ava --consent \
  --description "Late twenties, freckles, copper bob, oversized denim jacket" \
  --persona '{"niche":"Fashion · fit checks","voice":"Dry, quick, never salesy"}' \
  --style-pack "Phone snap" --style-pack "Quiet luxury" \
  --image ./ava-front.jpg --image ./ava-profile.jpg --image fil_01J9B...

{
  "id": "chr_01J9CD...",
  "object": "character",
  "name": "Ava",
  "description": "Late twenties, freckles, copper bob, oversized denim jacket",
  "status": "training",
  "source_images": ["fil_01J9A...", "fil_01J9C...", "fil_01J9B..."],
  "thumbnail_url": null,
  "reason": null,
  "scope": "organization",
  "persona": { "niche": "Fashion · fit checks", "voice": "Dry, quick, never salesy" },
  "style_pack": ["Phone snap", "Quiet luxury"],
  "sheet": [],
  "metadata": {
    "consent": {
      "attested": true,
      "by": "key_01J8ZX...",
      "at": "2026-10-15T12:00:00.000Z",
      "statement": "I confirm the person in these photos is me, or has given me permission to create an AI likeness of them, and is not a public figure."
    }
  },
  "created_at": "2026-10-15T12:00:00.000Z",
  "updated_at": "2026-10-15T12:00:00.000Z"
}

Flag	Description
`--name`	Required. A short name unique among your characters, 1–100 characters. How you address it later.
`--description`	Who the character is — looks, age, vibe, wardrobe. Up to 1,024 characters.
`--image`	Required, repeat for one to sixteen photos of the same person. Each is a public `http(s)` URL, a stored `fil_` id, or a local `png`/`jpg`/`jpeg`/`webp`/`gif`/`heic` file — uploaded to Files first and sent as its `fil_`. More, varied angles train a stronger likeness.
`--persona`	Who they are, as a JSON object of up to five lines of 500 characters: `niche`, `bio`, `voice`, `wardrobe`, `hooks` — read by your agents when they write as the character.
`--style-pack`	Repeat, one look name each (as `--style` takes them, up to 12): the looks the character is usually drawn in.
`--consent`	Required. You confirm the person in the photos is you, or has given you permission to create an AI likeness of them, and is not a public figure. Without it nothing is sent. The character keeps who confirmed it and when.

Photos of a recognizable public figure are refused before anything is billed, with the reason. A training is billed once, when the trainer accepts the photos; your balance must cover one first, else insufficient_credits. The CLI sends the required Idempotency-Key for you. Re-running the same command is refused before anything is trained, because the name is taken — delete the character first to train it again. See Billing.

get

vetta character get Ava | jq -r .status

Each read advances the status from the trainer: training, then ready or failed (with reason). Poll it until it is ready:

until [ "$(vetta character get Ava | jq -r .status)" != training ]; do sleep 20; done

list

vetta character list --status ready

Flag	Description
`--status`	`training`, `ready` or `failed`.
`--scope`	`organization` (yours) or `platform` (prebuilt: ready now, with a `persona` and the `style_pack` looks they are usually drawn in; they cannot be deleted).
`--limit`	Page size, 1–100.
`--after`	The `next_cursor` of the previous page.

delete

vetta character delete Ava

{ "id": "chr_01J9CD...", "object": "character", "deleted": true }

A soft delete: the character can no longer be rendered as, and its name is free for a new one. Images it already rendered keep their source.character_id.

Rendering as a character

--character on vetta media generate renders an image as a ready character. With --image-url naming a still of that character (its fil_ id), it re-poses that still on the same set instead:

vetta media generate --kind image --character Ava \
  --prompt "Ava waves at the camera on a rooftop at golden hour" --aspect-ratio 9:16

vetta media generate --kind image --character Ava --image-url fil_01J9... \
  --prompt "closer, she leans on the railing and laughs" --aspect-ratio 9:16

A character carries into video through that still: pass --character and the still’s fil_ id as the video’s --image-url first frame. The first frame must be a still rendered as that character, or the call is refused, and only a model that animates a still is used:

vetta media generate --kind video --character Ava --image-url fil_01J9... --prompt "she waves, the camera pushes in slowly"

An agent does the same with the create_character family of tools; a character made here is one its sessions can render as.

Getting started

Building & running

Organization

Identity

vetta character

Commands

create

get

list

delete

Rendering as a character

​Commands

​create

​get

​list

​delete

​Rendering as a character

Commands

create

get

list

delete

Rendering as a character