Skip to main content
POST
/
v1
/
characters
/
{id}
/
resynthesize
Resynthesize all ref poses (synchronous)
curl --request POST \
  --url https://api.aurous-labs.com/v1/characters/{id}/resynthesize \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "force_all": true
}
'
{
  "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",
  "client_reference_id": "bot_8472",
  "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"
}
POST /v1/characters/{id}/resynthesize re-runs the synthesize pipeline against the character’s existing attributes to produce a fresh set of ref poses. Use it when:
  • The synthesize-flow create result was a complete miss and individual regenerate-ref calls aren’t enough.
  • A failed synthesis needs another full attempt.
  • You want to “reroll” a character without changing its identity attributes.
The character transitions to status: synthesizing. Poll GET /v1/characters/{id} until status returns to reviewing (then call POST /v1/characters/{id}/save) or ready. The endpoint returns 200 with the updated character resource (Stripe pattern — the resource exists and this is a state transition). This endpoint costs credits — same cost as the original synthesize-flow create (4 generations). Estimate via POST /v1/images/estimate on the equivalent prompt if you need a budget guardrail.

​
Body

FieldRequiredDescription
force_allnoWhen true, regenerate every pose even if some are already populated. Default false — the behaviour is to replace the full ref set anyway, so this flag is mainly forward-compat for partial-resync semantics.

​
Examples

curl -X POST https://api.aurous-labs.com/v1/characters/char_01HXMQ7Z3K8Y2ABCDEFGHJKM/resynthesize \
  -H "X-Api-Key: $AUROUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

​
Limits

  • Rate limit: bucket characters_synthesize — 6 requests/min sustained, 12 burst per team. Shared with synthesize-flow create and regenerate-ref.
  • 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 4 paid generations, so a network retry without a key can multiply your bill.

​
Errors

CodeHTTPWhen
invalid_request_error400Character is in a non-resynthesizable state. Eligible states: reviewing, ready, failed.
insufficient_credits402Team credits < the resynthesize cost.
resource_not_found404Unknown ID, soft-deleted character, or cross-team.
idempotency_key_in_use409Same Idempotency-Key used with a different body, or previously used on a different route.
rate_limit_exceeded429Burst > 12 or sustained > 6/min.

​
Common pitfalls

  • resynthesize is the most expensive character endpoint — always pass Idempotency-Key to avoid double-charges on retry.
  • Resynthesizing a ready character moves it back to synthesizing. Existing generations referencing it on GET /v1/images/{id} are unaffected; only future requests pick up the new refs.
  • 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.

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

Path Parameters

​
id
string
required

Opaque character ID

Example:

"char_01HXMQ7Z3K8Y2NABCDEFGHJKMR"

Body

application/json
​
force_all
boolean

Reserved (no-op today). Resynthesize always regenerates all 4 ref poses in the current API version, so this flag has no effect regardless of its value. It is accepted for forward-compatibility with a future partial-resynthesis mode (regenerate only missing/failed poses).

Example:

true

Response

Ref poses resynthesized; updated character returned

​
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

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

Example:

"bot_8472"

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