> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnichar.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Characters API: create, check and retrain

> Create a character from 4-12 face photos plus optional body photos and voice, check its build status, download the .char, and retrain it as a new version.

A character is built from photos you [upload](https://docs.omnichar.org/api/uploads.md) first. Creating one returns an id at once; the build runs in the background and you hear about the result through a [webhook](https://docs.omnichar.org/api/webhooks.md) or by polling.

## Create a character

`POST /v1/chars` · scope `chars:write`

```bash theme={null}
curl -s -X POST https://api.omnichar.org/v1/chars \
  -H "Authorization: Bearer $OMNICHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-subject-001" \
  -d '{
    "subject_id": "subject-001",
    "references": {
      "face": ["inputs/.../1.png", "inputs/.../2.png", "inputs/.../3.png", "inputs/.../4.png"],
      "body": ["inputs/.../full-length.jpg"],
      "voice": "inputs/.../voice.mp3"
    },
    "description": "Calm presenter, mid-thirties",
    "provider_receipt": { "provider": "consent-co", "receipt_id": "rcpt_8812" },
    "callback_url": "https://example.com/omnichar/events"
  }'
```

```json theme={null}
{ "id": "7f1c2a9e-...", "status": "queued", "version": 1 }
```

| Field | Required | Notes |
| - | - | - |
| `subject_id` | yes | Your pseudonymous id for the person, up to 120 characters. Not a name. |
| `references.face` | yes | 4 to 12 upload keys of face photos (PNG, JPEG or WebP). At most 20 files across face, body and voice. |
| `references.body` | no | Up to 12 upload keys of body photos. |
| `references.voice` | no | One upload key of an audio clip (MP3, WAV, M4A, AAC, FLAC or OGG). |
| `description` | no | Up to 2,000 characters. It is checked against the content policy before the build starts. |
| `provider_receipt` | no | Your consent provider's record, stored as sent and embedded in the `.char` file. |
| `callback_url` | no | An HTTPS URL that also receives this character's `char.*` events. |

Each reference is the `upload_key` from [`POST /v1/uploads`](https://docs.omnichar.org/api/uploads), either as a plain string or as `{ "upload_key": "..." }`. An upload belongs to the person who created the API key that made it, so use keys created by the same person for uploading and creating; see [Who can use an upload](https://docs.omnichar.org/api/uploads.md#who-can-use-an-upload).

In production a build uses one build from your team's balance, or credits once builds run out. It is charged only when it produces a character; a failed build gives the build back. In sandbox nothing is charged and the build is mocked: see [Sandbox](https://docs.omnichar.org/api/sandbox.md).

## Check a character

`GET /v1/chars/{id}` · scope `chars:read`

```bash theme={null}
curl -s https://api.omnichar.org/v1/chars/$CHAR_ID -H "Authorization: Bearer $OMNICHAR_API_KEY"
```

```json theme={null}
{
  "id": "7f1c2a9e-...",
  "subject_id": "subject-001",
  "status": "ready",
  "version": 1,
  "env": "production",
  "description": "Calm presenter, mid-thirties",
  "provider_receipt_present": true,
  "failure_reason": null,
  "download_url": "https://...",
  "created_at": "2026-11-09T10:02:11.000Z",
  "updated_at": "2026-11-09T10:09:40.000Z"
}
```

`status` is `queued`, `building`, `ready` or `failed`. `download_url` points at the latest ready `.char` and lasts at least 45 minutes; ask again for a fresh one.

Every `.char` the API delivers carries a `reserved.provider` block in its manifest: your team id, the character id, the version, and `receipt`, which holds your `provider_receipt` or `null` when none was sent.

## Retrain a character

`POST /v1/chars/{id}/retrain` · scope `chars:write`

Retraining builds a new version from new references. The previous version stays downloadable until the new one is ready, and a successful retrain sends `char.updated`.

```bash theme={null}
curl -s -X POST https://api.omnichar.org/v1/chars/$CHAR_ID/retrain \
  -H "Authorization: Bearer $OMNICHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "references": { "face": ["inputs/...", "inputs/...", "inputs/...", "inputs/..."] } }'
```

```json theme={null}
{ "id": "7f1c2a9e-...", "status": "queued", "version": 2 }
```

A production retrain uses one build from the balance, exactly like a new character. You cannot retrain while a version is still building; that answers `409`.


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