Update a character
curl --request PATCH \
--url https://api.aurous-labs.com/v1/characters/{id} \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"name": "Aurora the Bold",
"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"
}
}
'import requests
url = "https://api.aurous-labs.com/v1/characters/{id}"
payload = {
"name": "Aurora the Bold",
"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"
}
}
headers = {
"X-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Aurora the Bold',
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'
}
})
};
fetch('https://api.aurous-labs.com/v1/characters/{id}', 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}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Aurora the Bold',
'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'
]
]),
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}"
payload := strings.NewReader("{\n \"name\": \"Aurora the Bold\",\n \"attributes\": {\n \"gender\": \"female\",\n \"age\": 28,\n \"ethnicity\": \"east-asian\",\n \"hair_color\": \"black\",\n \"hair_style\": \"shoulder-length straight\",\n \"eye_color\": \"brown\",\n \"body_type\": \"athletic\",\n \"additional_details\": \"small scar above right eyebrow; warm smile\"\n }\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://api.aurous-labs.com/v1/characters/{id}")
.header("X-Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Aurora the Bold\",\n \"attributes\": {\n \"gender\": \"female\",\n \"age\": 28,\n \"ethnicity\": \"east-asian\",\n \"hair_color\": \"black\",\n \"hair_style\": \"shoulder-length straight\",\n \"eye_color\": \"brown\",\n \"body_type\": \"athletic\",\n \"additional_details\": \"small scar above right eyebrow; warm smile\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.aurous-labs.com/v1/characters/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Aurora the Bold\",\n \"attributes\": {\n \"gender\": \"female\",\n \"age\": 28,\n \"ethnicity\": \"east-asian\",\n \"hair_color\": \"black\",\n \"hair_style\": \"shoulder-length straight\",\n \"eye_color\": \"brown\",\n \"body_type\": \"athletic\",\n \"additional_details\": \"small scar above right eyebrow; warm smile\"\n }\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"
}
}Characters
Update a character
Edit a character’s name and attributes. Refs are immutable.
PATCH
/
v1
/
characters
/
{id}
Update a character
curl --request PATCH \
--url https://api.aurous-labs.com/v1/characters/{id} \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"name": "Aurora the Bold",
"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"
}
}
'import requests
url = "https://api.aurous-labs.com/v1/characters/{id}"
payload = {
"name": "Aurora the Bold",
"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"
}
}
headers = {
"X-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Aurora the Bold',
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'
}
})
};
fetch('https://api.aurous-labs.com/v1/characters/{id}', 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}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Aurora the Bold',
'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'
]
]),
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}"
payload := strings.NewReader("{\n \"name\": \"Aurora the Bold\",\n \"attributes\": {\n \"gender\": \"female\",\n \"age\": 28,\n \"ethnicity\": \"east-asian\",\n \"hair_color\": \"black\",\n \"hair_style\": \"shoulder-length straight\",\n \"eye_color\": \"brown\",\n \"body_type\": \"athletic\",\n \"additional_details\": \"small scar above right eyebrow; warm smile\"\n }\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://api.aurous-labs.com/v1/characters/{id}")
.header("X-Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Aurora the Bold\",\n \"attributes\": {\n \"gender\": \"female\",\n \"age\": 28,\n \"ethnicity\": \"east-asian\",\n \"hair_color\": \"black\",\n \"hair_style\": \"shoulder-length straight\",\n \"eye_color\": \"brown\",\n \"body_type\": \"athletic\",\n \"additional_details\": \"small scar above right eyebrow; warm smile\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.aurous-labs.com/v1/characters/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Aurora the Bold\",\n \"attributes\": {\n \"gender\": \"female\",\n \"age\": 28,\n \"ethnicity\": \"east-asian\",\n \"hair_color\": \"black\",\n \"hair_style\": \"shoulder-length straight\",\n \"eye_color\": \"brown\",\n \"body_type\": \"athletic\",\n \"additional_details\": \"small scar above right eyebrow; warm smile\"\n }\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"
}
}PATCH /v1/characters/{id} updates the mutable fields of a character: name and attributes. Send only the fields you want to change. Omitted fields are preserved.
The reference images themselves (refs[]) are immutable by design — the cover image is the first ref in synthesize order or the first uploaded ref, and is not customer-controllable in v1.0. To change the visual identity, regenerate a single pose via POST /v1/characters/{id}/refs/regenerate or rerun the whole synthesis via POST /v1/characters/{id}/resynthesize.
When to use
- Renaming a character.
- Updating
attributes.additional_detailsto add notes you want to surface in your UI.
Examples
curl -X PATCH https://api.aurous-labs.com/v1/characters/char_01HXMQ7Z3K8Y2VNABCDEFGHJKM \
-H "X-Api-Key: $AUROUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Aurora (final)"}'
const updated = await fetch(
`https://api.aurous-labs.com/v1/characters/${id}`,
{
method: "PATCH",
headers: {
"X-Api-Key": process.env.AUROUS_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify({ name: "Aurora (final)" }),
},
).then((r) => r.json());
import os, requests
r = requests.patch(
f"https://api.aurous-labs.com/v1/characters/{character_id}",
headers={"X-Api-Key": os.environ["AUROUS_API_KEY"]},
json={"name": "Aurora (final)"},
).json()
Limits
- Rate limit: bucket
characters_post— 30 requests/min sustained, 60 burst per team.
Errors
| Code | HTTP | When |
|---|---|---|
resource_not_found | 404 | Unknown ID, soft-deleted character, or cross-team. error.param is "character_id". |
invalid_request | 400 | Body validation failure (e.g. name over the length cap). error.param names the offending field. |
Common pitfalls
- The platform applies a strict whitelist server-side. Sending fields outside the v1.0 mutable set (
name,attributes) — for examplerefs,id,team_id,status, oraurous_version— returns400 invalid_requestwitherror.paramnaming the first rejected field and a message listing every offending key. This is intentional: a silent-ignore policy would let a buggy client believe a non-existent field had taken effect. If you need a field to be mutable, send a feature request — new mutable fields land in v1.1 schema bumps. - PATCH on a
deletedcharacter returns 404resource_not_found— revive flows are not part of v1.0. attributesis not deep-merged; sendingattributes: { eye_color: "blue" }replaces the whole object. Re-send all fields you want preserved.
Authorizations
Your team API key (starts with al_live_).
Headers
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
Opaque character ID
Example:
"char_01HXMQ7Z3K8Y2NABCDEFGHJKMR"
Body
application/json
Response
Updated character
Opaque character ID.
Example:
"char_01HXMQ7Z3K8Y2NABCDEFGHJKMR"
Discriminator
Available options:
character Example:
"character"
Display name.
Example:
"Aurora the Adventurer"
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"
Reference images (typically 4 poses).
Show child attributes
Show child attributes
Creation timestamp (ISO 8601).
Example:
"2026-05-08T10:00:00Z"
Last-update timestamp (ISO 8601).
Example:
"2026-05-08T10:00:00Z"
Caller-supplied reference echoed back (the value sent on create). Null if unset.
Example:
"bot_8472"
Character attributes. Null when unset.
Show child attributes
Show child attributes
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
API contract version applied at the time this row was minted (D25 — frozen for replay across future version bumps).
Example:
"2026-08-26"