Characters API: create, check and retrain

A character is built from photos you upload first. Creating one returns an id at once; the build runs in the background and you hear about the result through a webhook or by polling.

Create a character

POST /v1/chars · scope chars:write

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"
  }'

{ "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, 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. 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.

Check a character

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

curl -s https://api.omnichar.org/v1/chars/$CHAR_ID -H "Authorization: Bearer $OMNICHAR_API_KEY"

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

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/..."] } }'

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

Get started

Omnichar Cloud

Omnichar Studio

ComfyUI node

API

API reference

Integrations

Characters API: create, check and retrain

Create a character

Check a character

Retrain a character