Skip to main content
POST
Create a character (upload OR synthesize flow) — async
POST /v1/characters creates a character — a reusable identity asset you can attach to an image or video generation via character_id (see Create an image or Create a video). There are two mutually exclusive flows:
  • Upload flow: pass upload_ids (1–6) collected from POST /v1/characters/uploads/init. The platform moves the bytes to character storage and the response comes back with status: ready — immediately usable.
  • Synthesize flow: pass generate: true plus an attributes object describing who the character is. The platform dispatches a multi-image generation task that produces 4 ref poses (portrait, front, side, back). The response returns status: synthesizing while generation is in flight, or status: reviewing if synthesis completed before the response returned (typical for fast runs). Either way, poll GET /v1/characters/{id} until status: reviewing, then call POST /v1/characters/{id}/save to mark it ready.
Send upload_ids or generate: true — never both, never neither. Sending both or neither returns 400 parameter_invalid_combination.

​
Upload flow

Use this when you already have ref images. Mint one upload_id per file via POST /v1/characters/uploads/init, PUT the bytes, then create the character.

​
Synthesize flow

Use this when you want the platform to generate the refs from a description. The attributes object is locked at v1.0 to 7 typed fields plus a free-text additional_details catch-all; on this synthesize flow every field drives generation (on the upload flow only additional_details is used, and only as a best-effort hint — see Upload flow). Synthesize burns credits at create time (4 generation dispatches), so prefer to estimate cost via POST /v1/images/estimate on the equivalent prompt if you need a budget guardrail in your UI.

​
Status transitions

​
Limits

  • Rate limit: bucket characters_synthesize — 15 requests/min sustained, 30 burst per team. Both flows ride this bucket since the synthesize discriminator is decided server-side after the request lands.
  • Idempotency: pass Idempotency-Key (any opaque value, 1–256 chars). Same key + same body within 24h replays the cached response with Aurous-Idempotent-Replayed: true. Same key + different body returns 409 idempotency_key_in_use. See Idempotency for details.
Always send Idempotency-Key on synthesize-flow create — it dispatches 4 paid generations, so a network retry without a key can double-charge.

​
Errors

​
Common pitfalls

  • The synthesize flow returns 201 immediately, but the character is not usable until it transitions to ready — either automatically (upload flow) or via POST /v1/characters/{id}/save (synthesize flow). Calling POST /v1/images or POST /v1/videos with a synthesizing or reviewing character_id returns 400 character_not_ready.
  • An upload flow with a single ref still works. On the upload flow your reference images define identity, so the 7 typed attributes (gender, age, etc.) are stored and echoed back but do not shape the generated refs — only additional_details is applied there, and only as a best-effort hint (your reference images are the primary signal). The synthesize flow (generate: true) is the opposite: all attributes drive generation, so don’t send empty attributes there.
  • The attributes schema is locked for v1.0; new attributes go into additional_details until a v1.1 bump introduces them as typed fields.

Authorizations

​
X-Api-Key
string
header
required

Your team API key (starts with al_live_).

Headers

​
Idempotency-Key
string

Stripe-style idempotency key (1-256 chars). Same key + same canonical-JSON body returns the cached response with Aurous-Idempotent-Replayed: true. Same key against a different route (e.g. previously used on /v1/images) returns 409 invalid_request / idempotency_key_in_use. Replay window is 24 hours. Absent header is treated as non-idempotent (each call processes anew).

​
Aurous-Version
string

Optional API version pin (YYYY-MM-DD). Omit the header to receive the platform default, currently 2026-08-26.

Pattern: ^\d{4}-\d{2}-\d{2}$
Example:

"2026-08-26"

Body

application/json
​
name
string
required

Display name for the character (1-80 chars).

Required string length: 1 - 80
Example:

"Aurora the Adventurer"

​
generate
boolean

Selects the synthesize flow when true (the platform generates 4 ref poses from attributes). When omitted/false, upload_ids must be provided to attach customer-supplied refs. Mutually exclusive with upload_ids.

Example:

false

​
upload_ids
string[]

Upload tickets from POST /v1/characters/uploads/init (1-6). When set, the upload flow is used and the server moves bytes from upload storage to character storage on create (uploads are consumed). Mutually exclusive with generate: true.

Required array length: 1 - 6 elements
Example:
​
attributes
object

Character attributes. Required when generate: true (synthesize flow), where ALL fields drive generation. Optional on the upload flow, where the 7 typed fields (gender, age, ethnicity, hair_color, hair_style, eye_color, body_type) are stored and echoed back but do NOT shape the generated refs — your uploaded images define identity. additional_details is the exception: it is also applied on the upload flow as a free-text styling hint, but treat it as best-effort — your uploaded reference images are the primary signal, so supply a reference image for any trait you need to guarantee.

​
client_reference_id
string

Optional caller-supplied reference, echoed back on GET /v1/characters/{id} and in every character webhook for this character. Use it to correlate the webhook with the originating record in your system (Stripe-style). Immutable after create. Max 256 chars.

Maximum string length: 256
Example:

"bot_8472"

Response

Character accepted; synthesis dispatched (status: synthesizing, refs: []).

​
id
string
required

Opaque character ID.

Example:

"char_01HXMQ7Z3K8Y2NABCDEFGHJKMR"

​
object
enum<string>
required

Discriminator

Available options:
character
Example:

"character"

​
name
string
required

Display name.

Example:

"Aurora the Adventurer"

​
status
enum<string>
required

Lifecycle state. synthesizing: synthesize flow running. reviewing: synthesize completed, awaiting POST /:id/save. ready: usable on POST /v1/images. failed: synthesize failed; use POST /:id/resynthesize to retry. deleted: soft-deleted (filtered out of list endpoint).

Available options:
synthesizing,
reviewing,
ready,
failed,
deleted
Example:

"ready"

​
refs
object[]
required

Reference images (typically 4 poses).

​
created_at
string
required

Creation timestamp (ISO 8601).

Example:

"2026-05-08T10:00:00Z"

​
updated_at
string
required

Last-update timestamp (ISO 8601).

Example:

"2026-05-08T10:00:00Z"

​
client_reference_id
object | null

Caller-supplied reference echoed back (the value sent on create). Null if unset.

Example:

"bot_8472"

​
attributes
object | null

Character attributes. Null when unset.

​
error_message
object | null

Machine-readable failure code from the most recent synthesize/resynthesize attempt. One of synthesis_failed, synthesis_timeout, provider_unavailable — a closed set to switch on, not customer-facing prose. Null when the most recent attempt succeeded (or none has run yet). Set on failed, but NOT failed-exclusive: a failed resynthesize restores the character to its prior working status (reviewing) rather than overwriting a good generation, so a reviewing row can carry a non-null code here — check this field for failure, not status. Cleared on the next resynthesize attempt and on success.

Example:

null

​
aurous_version
string

API contract version applied at the time this row was minted (D25 — frozen for replay across future version bumps).

Example:

"2026-08-26"