> ## 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 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](/docs/api/characters.md).

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

```bash theme={"system"}
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...
```

```json theme={"system"}
{
  "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](/docs/cli/files.md) 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`](/docs/cli/media#generate) 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](/docs/api/characters.md#billing).

## get

```bash theme={"system"}
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`:

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

## list

```bash theme={"system"}
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

```bash theme={"system"}
vetta character delete Ava
```

```json theme={"system"}
{ "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`](/docs/cli/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:

```bash theme={"system"}
vetta media generate --kind image --character Ava \
  --prompt "Ava waves at the camera on a rooftop at golden hour" --aspect-ratio 9:16
```

```bash theme={"system"}
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:

```bash theme={"system"}
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](/docs/capabilities/tools#characters); a character made here is one its sessions can render as.


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