Skip to main content
POST
Resynthesize every generated view (synchronous)
POST /v1/characters/{id}/resynthesize re-runs the synthesize pipeline against the character’s existing attributes. It re-renders all eight views except any you uploaded, priced at build.per_view_credits per view it re-renders — so an older character carrying fewer than eight comes back with all eight, priced at 8 × build.per_view_credits. The eight are head_front, upper_front, lower_front, upper_back, lower_back, full_left, full_front, full_right. Generated views only. References you uploaded yourself — views[].status: "uploaded" — are left untouched: not re-rendered, not removed, and not charged for. Read views[] before you call to know what this will actually cost. If every reference on the character is one of your own photos there is nothing left to re-render, and the call returns 400 invalid_request (param: character_id) rather than doing nothing for a fee. The endpoint accepts characters in reviewing or failed state. The call is synchronous: the response returns the updated character with status: reviewing and its fresh refs. Review the refs, then call POST /v1/characters/{id}/save to move the character to ready. It renders eight views in one request, so set a client timeout of at least 600 seconds. Aborting client-side does not cancel the render. If the render itself cannot be completed, the call returns 503 provider_unavailable with a Retry-After header, the credits charged for that call are refunded automatically, and the character keeps the status it had — retry when Retry-After elapses. The endpoint returns 200 with the updated character resource (Stripe pattern — the resource exists and this is a state transition). This endpoint costs credits — build.per_view_credits per view it re-renders, the same per-view price a create pays. Read build.per_view_credits off the character rather than hard-coding it.

​
Body

​
Examples

​
Limits

  • 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.
  • Idempotency: pass Idempotency-Key (any opaque value, 1–256 chars). Same key + same body within 24h replays the cached response. Same key + different body returns 409 idempotency_key_in_use. See Idempotency.
Always pass Idempotency-Key — this endpoint dispatches one paid generation per view it re-renders, so a network retry without a key can multiply your bill.

​
Errors

​
Common pitfalls

  • resynthesize is the most expensive character endpoint — always pass Idempotency-Key to avoid double-charges on retry.
  • Resynthesize works on both reviewing and failed characters — it’s the primary way to retry a failed synthesis, reusing the character’s stored attributes. If the character’s original uploaded photos have since expired, the call returns 422 uploads_expired instead (this endpoint doesn’t accept new photos on resynthesize); in that case, delete via DELETE /v1/characters/{id} and recreate via POST /v1/characters with fresh upload_ids.
  • Resynthesize uses the stored attributes. If you want to change identity (e.g. different hair_color), call PATCH /v1/characters/{id} with the new attributes first, then resynthesize.
  • Resynthesize and build are not interchangeable. Resynthesize re-renders the generated views of a character created by POST /v1/characters, reading its original upload tickets. Build renders the missing views of a character you assembled yourself, and refuses a one-shot character (400 character_status_invalid) precisely because its photos are still tickets. Each route tells you to use the other when you pick wrong.

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
​
force_all
boolean

Reserved (no-op today). Resynthesize re-renders every generated view (uploaded references are kept); priced per view — see build.per_view_credits. That is what the current API version does regardless of this flag's value. It is accepted for forward-compatibility with a future partial-resynthesis mode (re-render only the missing or failed views).

Example:

true

Response

Ref poses resynthesized; updated character returned at status: reviewing

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