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-07-16"
}

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

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-07-16"
}

{
  "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_details to add notes you want to surface in your UI.

This endpoint does not trigger any inference or charge credits — it is purely metadata.

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 example refs, id, team_id, status, or aurous_version — returns 400 invalid_request with error.param naming 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 deleted character returns 404 resource_not_found — revive flows are not part of v1.0.
attributes is not deep-merged; sending attributes: { eye_color: "blue" } replaces the whole object. Re-send all fields you want preserved.

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-07-16 for unauthenticated requests.

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2026-07-16"

Path Parameters

string

required

Opaque character ID

Example:

"char_01HXMQ7Z3K8Y2NABCDEFGHJKMR"

Body

application/json

name

string

New display name (1-80 chars). Refs are immutable post-creation; use :id/refs/regenerate or :id/resynthesize to change them.

Required string length: 1 - 80

Example:

"Aurora the Bold"

attributes

object

Updated character attributes (full replace, not merge).

Show child attributes

Response

Updated character

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

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-07-16"

Get started

Guides

Concepts

API Reference

Resources

Update a character

When to use

Examples

Limits

Errors

Common pitfalls

Authorizations

Headers

Path Parameters

Body

Response

​When to use

​Examples

​Limits

​Errors

​Common pitfalls

Authorizations

Headers

Path Parameters

Body

Response

When to use

Examples

Limits

Errors

Common pitfalls