Regenerate a single ref pose

Regenerate a single ref pose (synchronous)

curl --request POST \
  --url https://api.aurous-labs.com/v1/characters/{id}/refs/regenerate \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "pose": "front",
  "prompt_override": "soft studio lighting, neutral background"
}
'

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

characters

{id}

refs

regenerate

Regenerate a single ref pose (synchronous)

curl --request POST \
  --url https://api.aurous-labs.com/v1/characters/{id}/refs/regenerate \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "pose": "front",
  "prompt_override": "soft studio lighting, neutral background"
}
'

{
  "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}/refs/regenerate re-runs the synthesize pipeline for one pose, leaving the other refs intact. Use it when three of the four synthesized refs look right but the fourth needs another try. The endpoint returns 200 with the updated character resource (Stripe pattern — the resource exists and this is a state transition, not a new-resource creation). The character transitions to status: synthesizing while the new ref mints; poll GET /v1/characters/{id} until status returns to reviewing (then call POST /v1/characters/{id}/save) or ready. This endpoint costs credits — one generation per call. Estimate cost via POST /v1/images/estimate on the equivalent prompt if you need a budget guardrail in your UI.

When to use

The synthesize flow produced three good refs and one bad one; you want to fix only the bad one.
A failed regen needs another attempt without touching other poses.

If you want to regenerate all four poses, call POST /v1/characters/{id}/resynthesize instead.

Body

Field	Required	Description
`pose`	yes	One of `portrait`, `front`, `side`, `back`, `other`.
`prompt_override`	no	Forward-compat slot. Currently a no-op — the orchestrator does not honor it yet. Safe to omit.

Examples

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

Limits

Rate limit: bucket characters_synthesize — 6 requests/min sustained, 12 burst per team. Shared with synthesize-flow create and resynthesize.
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 a paid generation, so a network retry without a key can double-charge.

Errors

Code	HTTP	When
`invalid_request_error`	400	`pose` is not one of the canonical 5, or character is in a non-regen state.
`insufficient_credits`	402	Team credits < the regen cost.
`resource_not_found`	404	Unknown ID, soft-deleted character, or cross-team.
`idempotency_key_in_use`	409	Same `Idempotency-Key` used with a different body, or previously used on a different route.
`rate_limit_exceeded`	429	Burst > 12 or sustained > 6/min.

Common pitfalls

The pose enum is locked at v1.0 to portrait, front, side, back, other. Anything else is 400 invalid_request_error.
After regen, the character is synthesizing again. Polling resumes the same way as for fresh synthesis.
Regenerating from ready is allowed and moves the character back to synthesizing — existing generations that already reference the old ref are unaffected; only future requests pick up the new pose.

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

string

required

Opaque character ID

Example:

"char_01HXMQ7Z3K8Y2NABCDEFGHJKMR"

Body

application/json

pose

enum<string>

required

Which pose to regenerate. Must be one of the canonical V1 poses: portrait (head/shoulders), front (full-body facing camera), side (full-body in profile), back (full-body away from camera), or other.

Available options:

portrait,

front,

side,

back,

other

Example:

"front"

prompt_override

string

Optional prompt override for this single pose. Falls back to the character.attributes-derived prompt when omitted.

Example:

"soft studio lighting, neutral background"

Response

Ref pose regenerated; updated character returned

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

Show child attributes

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.

Show child attributes

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"

Delete a character Save a reviewing character

​When to use

​Body

​Examples

​Limits

​Errors

​Common pitfalls

Authorizations

Headers

Path Parameters

Body

Response

When to use

Body

Examples

Limits

Errors

Common pitfalls