Skip to main content
POST
Build the missing views
POST /v1/characters/{id}/build renders every view this character does not have a reference for, and leaves the ones you uploaded exactly as they are. It is the second half of the builder: create a draft, file your own photos into whichever views you have, then build the rest. The call is asynchronous: it returns immediately with status: "synthesizing".

​
When to use

  • A draft is as complete as you can make it from your own photos and you want the remaining views rendered.
  • A previous build failed and you want to retry — see Retrying a failed build.

​
Identity

The render needs something to look like. Which rule applies depends on whether you uploaded anything at all — the two are not interchangeable: Anything else returns 422 build_requires_identity and charges nothing. So if you uploaded any photo, one of them must show the face; attributes stand in for a photo only when the character has no uploads at all (build accepts failed characters too, not only drafts). The fix for a faceless set is another PUT — a head-view or full-body-front photo — not more attributes. Nothing was charged and nothing changed.

​
Price

build.per_view_credits × build.missing_views.length, charged up front. Read both off the character immediately before you build — they are configuration, not constants, and every accepted photo you file moves a view out of missing_views and lowers the total. build.cost_credits is that product, computed server-side from the references that exist right now. A render that fails releases its charge.

​
Examples

​
Body

What gets rendered is derived from the views still missing, never from the request body. There is no way to ask for a view the character already has — regenerate it instead.

​
Waiting for the result

Poll GET /v1/characters/{id} or subscribe to the character.completed / character.failed webhooks. Every view renders concurrently, each in roughly 60–180 seconds, so allow a few minutes end to end.

​
Nothing missing

If every view already holds a reference, there is nothing to render: the call returns 200 with no charge and no job, and the character goes straight to reviewing (or ready with auto_save). The character.completed webhook is still delivered — a fully-uploaded character produces exactly the same event a rendered one does, with operation: "create" like every other character event. Do not special-case it in your receiver.

​
Which statuses build

​
Retrying a failed build

failed is a deliberate entry point. A builder character’s uploaded references are stored on the character itself — real references, not expiring upload tickets — so rebuilding after a failure needs no re-upload and no new photos. (They do not outlive the character: photos you uploaded are removed when the draft is deleted or purged; a rejected upload is discarded after its 24-hour ticket window.)
While the character is failed, a view can be replaced with PUT /v1/characters/{id}/refs/{view} but not removed: DELETE /v1/characters/{id}/refs/{view} requires draft and answers 400 character_status_invalid here. Nothing was lost — swap the photo you want changed, then build again.

​
One-shot characters cannot build

A character created by POST /v1/characters is not builder lineage. Its source photos are still upload tickets, not references, so a build would render it from nothing and throw those photos away. It returns 400 character_status_invalid (param: character_id) with a message pointing at POST /v1/characters/{id}/resynthesize — that is the route that reads those tickets. Use resynthesize for a one-shot character, build for one you assembled yourself.

​
Limits

  • Cost: build.per_view_credits × build.missing_views.length, charged before the render is dispatched and released if the render fails. Zero views missing costs nothing.
  • Rate limit: bucket characters_synthesize — 15 requests/min sustained, 30 burst per team. Shared across POST /v1/characters, POST /v1/characters/{id}/refs/regenerate, POST /v1/characters/{id}/refs/{view}/regenerate, POST /v1/characters/{id}/resynthesize and POST /v1/characters/{id}/build — five routes, one bucket. See Rate limits.
  • 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.
Always send Idempotency-Key — a build dispatches one paid render per missing view, so a network retry without a key can double-charge.

​
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

  • Never hard-code the price. Read build.per_view_credits and build.missing_views off the character immediately before building; both move as you file photos.
  • The 200 is not a finished character. It means synthesizing — poll or take the webhook before you use the character_id.
  • Views you uploaded are never re-rendered by a build, and you are never charged for them. That is the point of the builder.
  • A zero-cost build still emits character.completed. Receivers that assume “an event means a render happened” will be wrong.
  • auto_save: true skips the reviewing stop. If your product shows the customer the rendered set before committing, leave it false.

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"

Path Parameters

​
id
string
required

Opaque character ID

Example:

"char_01HXMQ7Z3K8Y2NABCDEFGHJKMR"

Body

application/json
​
auto_save
boolean

When true, the character lands directly at ready on success instead of reviewing. Use it if you do not run a human review step; you then never call POST /{id}/save. Default false (lands at reviewing).

Example:

false

Response

Build dispatched (synthesizing), or terminal immediately when nothing was missing

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