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"
}
'

import requests

url = "https://api.aurous-labs.com/v1/characters/{id}/refs/regenerate"

payload = {
    "pose": "front",
    "prompt_override": "soft studio lighting, neutral background"
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({pose: 'front', prompt_override: 'soft studio lighting, neutral background'})
};

fetch('https://api.aurous-labs.com/v1/characters/{id}/refs/regenerate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aurous-labs.com/v1/characters/{id}/refs/regenerate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'pose' => 'front',
    'prompt_override' => 'soft studio lighting, neutral background'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aurous-labs.com/v1/characters/{id}/refs/regenerate"

	payload := strings.NewReader("{\n  \"pose\": \"front\",\n  \"prompt_override\": \"soft studio lighting, neutral background\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.aurous-labs.com/v1/characters/{id}/refs/regenerate")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"pose\": \"front\",\n  \"prompt_override\": \"soft studio lighting, neutral background\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.aurous-labs.com/v1/characters/{id}/refs/regenerate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"pose\": \"front\",\n  \"prompt_override\": \"soft studio lighting, neutral background\"\n}"

response = http.request(request)
puts response.read_body

{
  "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-08-26"
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

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"
}
'

import requests

url = "https://api.aurous-labs.com/v1/characters/{id}/refs/regenerate"

payload = {
    "pose": "front",
    "prompt_override": "soft studio lighting, neutral background"
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({pose: 'front', prompt_override: 'soft studio lighting, neutral background'})
};

fetch('https://api.aurous-labs.com/v1/characters/{id}/refs/regenerate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aurous-labs.com/v1/characters/{id}/refs/regenerate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'pose' => 'front',
    'prompt_override' => 'soft studio lighting, neutral background'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aurous-labs.com/v1/characters/{id}/refs/regenerate"

	payload := strings.NewReader("{\n  \"pose\": \"front\",\n  \"prompt_override\": \"soft studio lighting, neutral background\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.aurous-labs.com/v1/characters/{id}/refs/regenerate")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"pose\": \"front\",\n  \"prompt_override\": \"soft studio lighting, neutral background\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.aurous-labs.com/v1/characters/{id}/refs/regenerate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"pose\": \"front\",\n  \"prompt_override\": \"soft studio lighting, neutral background\"\n}"

response = http.request(request)
puts response.read_body

{
  "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-08-26"
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

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_01HXMQ7Z3K8Y2VNABCDEFGHJKM/refs/regenerate \
  -H "X-Api-Key: $AUROUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"pose": "front"}'

const character = await fetch(
  `https://api.aurous-labs.com/v1/characters/${id}/refs/regenerate`,
  {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.AUROUS_API_KEY!,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({ pose: "front" }),
  },
).then((r) => r.json());

console.log(character.status); // "synthesizing"

import os, uuid, requests

r = requests.post(
    f"https://api.aurous-labs.com/v1/characters/{character_id}/refs/regenerate",
    headers={
        "X-Api-Key": os.environ["AUROUS_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"pose": "front"},
).json()

print(r["status"])  # "synthesizing"

Limits

Rate limit: bucket characters_synthesize — 15 requests/min sustained, 30 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_format`	400	`pose` is not one of the canonical 5.
`invalid_request`	400	Character is in a non-regen state.
`balance_too_low`	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.
`too_many_requests`	429	Burst > 30 or sustained > 15/min.

Common pitfalls

The pose enum is locked at v1.0 to portrait, front, side, back, other. Anything else is 400 invalid_format.
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

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

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

Show child attributes

error_message

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

Get started

Guides

Concepts

API Reference

Resources

Regenerate a single ref pose

When to use

Body

Examples

Limits

Errors

Common pitfalls

Authorizations

Headers

Path Parameters

Body

Response

​When to use

​Body

​Examples

​Limits

​Errors

​Common pitfalls

Authorizations

Headers

Path Parameters

Body

Response

When to use

Body

Examples

Limits

Errors

Common pitfalls