Skip to main content
POST
/
v1
/
characters
Create a character (upload OR synthesize flow)
curl --request POST \
  --url https://api.aurous-labs.com/v1/characters \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "name": "Aurora the Adventurer",
  "generate": false,
  "upload_ids": [
    "upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR"
  ],
  "attributes": {
    "gender": "female",
    "age": 28,
    "ethnicity": "east-asian",
    "hair_color": "black",
    "hair_style": "shoulder-length straight",
    "eye_color": "brown",
    "body_type": "athletic",
    "additional_details": "small scar above right eyebrow; warm smile"
  }
}
'
{
  "id": "char_01HXMQ7Z3K8Y2NABCDEFGHJKMR",
  "object": "character",
  "name": "Aurora the Adventurer",
  "status": "ready",
  "refs": [
    {
      "pose": "front",
      "url": "https://api.aurous-labs.com/storage/.../front.bin?token=…"
    }
  ],
  "created_at": "2026-05-08T10:00:00Z",
  "updated_at": "2026-05-08T10:00:00Z",
  "attributes": {
    "gender": "female",
    "age": 28,
    "ethnicity": "east-asian",
    "hair_color": "black",
    "hair_style": "shoulder-length straight",
    "eye_color": "brown",
    "body_type": "athletic",
    "additional_details": "small scar above right eyebrow; warm smile"
  },
  "error_message": null,
  "aurous_version": "2026-05-15"
}

Documentation Index

Fetch the complete documentation index at: https://docs.aurous-labs.com/llms.txt

Use this file to discover all available pages before exploring further.

POST /v1/characters creates a character — a reusable identity asset you can attach to any image generation via character_id. 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. 
curl -X POST https://api.aurous-labs.com/v1/characters \
  -H "X-Api-Key: $AUROUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Aurora",
    "upload_ids": [
      "upl_01HXMQ7Z3K8Y2ABCDEFGHJKM",
      "upl_01HXMQ87RKZQA0YBYV1V47TPS6"
    ]
  }'

​
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 a small set of typed fields plus a free-text additional_details catch-all. 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. 
curl -X POST https://api.aurous-labs.com/v1/characters \
  -H "X-Api-Key: $AUROUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Aurora",
    "generate": true,
    "attributes": {
      "gender": "female",
      "age": 28,
      "ethnicity": "northern european",
      "hair_color": "auburn",
      "hair_style": "long waves",
      "eye_color": "green",
      "body_type": "athletic",
      "additional_details": "scar across left cheekbone, freckles"
    }
  }'

​
Status transitions

FlowInitialAfter processingCustomer action
Uploadready—Use immediately on POST /v1/images.
Synthesizesynthesizing (or reviewing if synth completed before the 201 returned)reviewingPoll GET /v1/characters/{id}. When reviewing, call POST /v1/characters/{id}/save to publish; or call POST /v1/characters/{id}/resynthesize to retry.
Synthesize (failed)synthesizingfailederror_message populated. Call POST /v1/characters/{id}/resynthesize to retry.

​
Limits

  • Rate limit: bucket characters_synthesize — 6 requests/min sustained, 12 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

CodeHTTPWhen
parameter_invalid_combination400Sent both upload_ids and generate: true, or neither.
upload_invalid400One of the upload_ids is unknown, expired, or already consumed.
insufficient_credits402Synthesize-flow dispatch when team credits < cost.
idempotency_key_in_use409Same Idempotency-Key was used with a different body.
rate_limit_exceeded429Burst > 12 or sustained > 6/min.

​
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 with a synthesizing or reviewing character_id returns 400 character_not_ready.
  • An upload flow with a single ref still works, but synthesis needs at least the typed attributes to anchor identity. Don’t pass empty attributes.
  • 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

​
Aurous-Version
string

Optional API version pin (YYYY-MM-DD). Defaults to your team's pinned version, or the system default 2026-05-15 for unauthenticated requests.

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

"2026-05-15"

​
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).

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:
["upl_01HXMQ7Z3K8Y2NABCDEFGHJKMR"]
​
attributes
object

Character attributes used by the synthesize flow. Required when generate: true. Optional on the upload flow (used as descriptive metadata only).

Response

Character created

​
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"

​
attributes
object

Character attributes. Null when unset.

​
error_message
object

Error message when status is failed. Null otherwise.

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-05-15"