vetta character

Train a reusable on-screen persona from reference photos, check on it, list and delete it — then render images as it with vetta media generate.

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 update <id|name>	Change its name, description, persona or looks. Never its face.
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.

​

update

vetta character update Ava --persona '{"wardrobe":"Linen shirts and old denim"}'

Takes --name, --description, --persona and --style-pack. A persona is merged line by line, so the lines you leave out stay. A prebuilt character is refused.

​

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.