Skip to main content
POST
/
v1
/
characters
/
{id}
/
refs
/
regenerate
Regenerate a single ref pose
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",
  "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"
}

Documentation Index

Fetch the complete documentation index at: https://docs.aurous-labs.com/llms.txt

Use this file to discover all available pages before exploring further.

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

FieldRequiredDescription
poseyesOne of portrait, front, side, back, other.
prompt_overridenoForward-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

CodeHTTPWhen
invalid_request_error400pose is not one of the canonical 5, or character is in a non-regen state.
insufficient_credits402Team credits < the regen 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

  • 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

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

Regen dispatched

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

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