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",
  "nudity": "clothed",
  "refs": [
    {
      "pose": "front",
      "view": "full_front",
      "source": "generated",
      "url": "https://storage-host.example/storage/v1/object/sign/characters/full_front.jpg?token=eyJhbGciOi..."
    }
  ],
  "views": [
    {
      "view": "full_front",
      "status": "generated",
      "url": null,
      "nudity": "clothed",
      "reason": null,
      "detected_view": null,
      "made_from": [
        "head_front",
        "full_front"
      ]
    }
  ],
  "build": {
    "missing_views": [
      "full_front",
      "full_right"
    ],
    "cost_credits": 123,
    "per_view_credits": 123
  },
  "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",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "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",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "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",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "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",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "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",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "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",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "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",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "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",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

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",
  "nudity": "clothed",
  "refs": [
    {
      "pose": "front",
      "view": "full_front",
      "source": "generated",
      "url": "https://storage-host.example/storage/v1/object/sign/characters/full_front.jpg?token=eyJhbGciOi..."
    }
  ],
  "views": [
    {
      "view": "full_front",
      "status": "generated",
      "url": null,
      "nudity": "clothed",
      "reason": null,
      "detected_view": null,
      "made_from": [
        "head_front",
        "full_front"
      ]
    }
  ],
  "build": {
    "missing_views": [
      "full_front",
      "full_right"
    ],
    "cost_credits": 123,
    "per_view_credits": 123
  },
  "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",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "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",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "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",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "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",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "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",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "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",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "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",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

{
  "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",
    "reason": "wrong_view",
    "detected_view": "full_left"
  }
}

Deprecated body form. Use POST /v1/characters/{id}/refs/{view}/regenerate, which reaches all eight named views. This route stays supported with no sunset date; its pose field resolves through a fixed alias table:

`pose`	View
`portrait`	`head_front`
`front`	`full_front`
`side`	`full_left`
`back`	`upper_back`
`other`	`400 invalid_format`

POST /v1/characters/{id}/refs/regenerate re-runs the synthesize pipeline for one view, leaving the other refs intact. Use it when one reference needs another try and the rest are fine — the pose you send is resolved through the alias table above, so this route can reach four of the eight named views. Every 2xx from this route carries Deprecation: true and a Link header with rel="successor-version" pointing at Regenerate a view, so the migration shows up in your logs. There is no Sunset header: no removal date has been announced. 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 call is synchronous: it blocks until the new ref is rendered and the response carries the updated character. It does not move the character to status: synthesizing — the status you sent it in (ready or reviewing) is the status it comes back with, so there is nothing to poll. This endpoint costs credits — one generation per call, charged before the render is dispatched. A render takes 60–180 seconds; set a client timeout of at least 300 seconds. Aborting the request client-side neither cancels the render nor refunds the credits. Read build.per_view_credits on any character response for the current per-view price — one call costs exactly that — if you need a budget guardrail in your UI.

When to use

One synthesized ref came back wrong and you want to fix only that one.
A failed regen needs another attempt without touching other poses.

To reach upper_front, lower_front, lower_back, full_right or any view by name, use POST /v1/characters/{id}/refs/{view}/regenerate. To regenerate the whole set, call POST /v1/characters/{id}/resynthesize instead.

Body

Field	Required	Description
`pose`	yes	One of `portrait`, `front`, `side`, `back` (alias table above); `other` is rejected.
`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); // unchanged — "ready" or "reviewing"

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"])  # unchanged — "ready" or "reviewing"

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 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 `portrait`, `front`, `side`, `back` — `other` included.
`character_status_invalid`	400	The character is not `ready` or `reviewing` (the message names the current status).
`reference_uploaded`	400	The view this `pose` resolves to holds a photo you uploaded. `param` is `view`. Replace it with `PUT /v1/characters/{id}/refs/{view}` instead. Nothing is charged.
`invalid_request`	400	The character has no references to condition the render on (zero refs).
`balance_too_low`	402	Team credits < the regen cost.
`resource_not_found`	404	Unknown ID, soft-deleted character, or cross-team.
`character_busy`	409	A render is in flight; retry after `Retry-After` seconds.
`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.
`provider_unavailable`	503	Synthesis is paused for your team; `Retry-After` is set.

Common pitfalls

The body pose enum accepts portrait, front, side, back. other and anything else is 400 invalid_format, and pose is resolved before the character is looked up — an unknown pose is a 400 even for an id that does not exist.
The character’s status does not change. The call blocks until the new ref exists and returns the updated character, so there is nothing to poll afterwards.
Regenerating from ready is allowed — existing generations that already reference the old ref are unaffected; only future requests pick up the new reference.
A view holding a photo you uploaded cannot be regenerated through either form of this route — it returns 400 reference_uploaded. Replace it with PUT /v1/characters/{id}/refs/{view}, or remove it from a draft and let a build render it. Read views[].status to tell the two apart.

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

deprecated

DEPRECATED body form — use POST /v1/characters/{id}/refs/{view}/regenerate, which reaches all eight views. This field keeps its original five values and resolves through a fixed alias table: portrait → head_front, front → full_front, side → full_left, back → upper_back. other is rejected with 400 invalid_format. No sunset date; the route stays supported.

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

Show child attributes

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

Show child attributes

build

object

required

What a build would render and cost right now. Always present.

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

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.

Show child attributes

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"

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