Skip to main content
POST
Create a character draft
POST /v1/characters/drafts creates a character in draft: no credits are charged and nothing is rendered. A draft is the empty shell the builder fills — file your own photos into its views with PUT /v1/characters/{id}/refs/{view}, then call POST /v1/characters/{id}/build to render whatever is still missing. A draft is not usable for generation: POST /v1/images or POST /v1/videos with its character_id returns 400 character_not_ready. Drafts appear in GET /v1/characters alongside everything else; filter with ?status=draft.
Compare with POST /v1/characters, the one-shot create: it charges for all eight views up front and renders them immediately. Use a draft when you want to supply some of the photos yourself and pay only for the views the platform actually renders.

​
When to use

  • You have your own photos for some views and want the platform to render only the rest.
  • You are building an upload UI and want a real character id to attach photos to before anything is charged.
  • You want to stage a character now and decide later whether to build it — an unbuilt draft costs nothing.

​
Examples

​
Body

​
Response

201 with the full character resource. On a fresh draft:
  • status is draft.
  • views[] has eight entries, every one status: "missing".
  • build.missing_views lists all eight; build.cost_credits is build.per_view_credits × 8 — what a build would charge right now. Every accepted photo you file takes a view off that list and lowers the quote.

​
Limits

  • Cost: free. A draft renders nothing and charges nothing. You are charged when you build.
  • Rate limit: bucket characters_post — 30 requests/min sustained, 60 burst per team. Shared with the other cheap character writes (uploads init/classify, PATCH, DELETE, view removal, save).
  • 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.

​
Errors

These changes ship on the existing 2026-08-26 contract. No Aurous-Version pin isolates them: the version catalogue carries image and video pricing pointers only, not character pricing or the size of the reference set. Pinning an earlier Aurous-Version restores neither the smaller reference set nor the previous price. A character created before 2026-09-14 keeps the references it already has — add either of the two newer views on demand with POST /v1/characters/{id}/refs/{view}/regenerate; every character created on or after that date carries eight.

​
Common pitfalls

  • A draft is free but not inert — it occupies an id and shows up in GET /v1/characters. Clean up the ones you abandon with DELETE /v1/characters/{id}, which hard-deletes a draft. Photos you uploaded are removed when the draft is deleted or purged; a rejected upload is discarded after its 24-hour ticket window.
  • nudity is only patchable while draft. Decide it here or with PATCH before you build; after the build there is no way to change it but to create a new character.
  • Sending attributes is not a substitute for a face once you have uploaded anything. If the draft holds any uploaded photo, one of them must clearly show the face — a faceless body photo plus attributes is still 422 build_requires_identity. attributes stand in for a photo only when the draft has no uploads.
  • Read the view vocabulary from GET /v1/characters/views and the slot semantics from Views and lifecycle; don’t hardcode the eight names.

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"

​
nudity
enum<string>

Whether this character's reference set is nude or clothed. Immutable once the character leaves draft — set it here, or with PATCH while still a draft. Omit to accept your team's default. On teams that always render clothed an explicit nude returns 400 nudity_not_allowed.

Available options:
nude,
clothed
Example:

"clothed"

​
attributes
object

Character attributes. Optional on a draft. They satisfy the build-time identity rule ONLY for a draft with no uploaded photos at all: once the draft holds any uploaded photo, one of those photos must show the face and attributes are not consulted — see POST /v1/characters/{id}/build.

​
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

Draft 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. draft: references are being assembled; nothing has been charged and the character cannot be used for generation. New lifecycle states may be added in future — treat any status other than ready as "not yet usable". synthesizing: references are being built. ready: usable on POST /v1/images — both create flows advance here on their own. reviewing: reached only after POST /:id/resynthesize or POST /:id/build; call POST /:id/save to return to ready. failed: the build failed; error_message carries the reason and POST /:id/build (builder characters) or POST /:id/resynthesize retries. deleted: soft-deleted (filtered out of the list endpoint).

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

"ready"

​
nudity
enum<string>
required

What the reference set is rendered as — nude unless you chose clothed, or — when you omitted nudity — your team's default is clothed. An explicit value always wins. Fixed once the references are built.

Available options:
nude,
clothed
Example:

"clothed"

​
refs
object[]
required

Reference images, one per view the character has. A character built today has eight; an older one can have fewer than eight (typically six, some of the oldest four). Do not assume a count — read views[], the canonical read model for new integrations, or build.missing_views. refs[] lists only the references that exist.

​
views
object[]
required

One entry per named view, in canonical order — every reference that maps to a named view, keyed by view, plus what is missing or was rejected. A reference from before named views existed (refs[].view is other) appears only in refs[].

​
build
object
required

What a build would render and cost right now. Always present.

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