Skip to main content
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"
  }
}
'
{
  "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-05-15"
}
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_01HXMQ7Z3K8Y2ABCDEFGHJKM \
  -H "X-Api-Key: $AUROUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Aurora (final)"}'

​
Limits

  • Rate limit: bucket characters_post — 30 requests/min sustained, 60 burst per team.

​
Errors

CodeHTTPWhen
resource_not_found404Unknown ID, soft-deleted character, or cross-team. error.param is "character_id".
invalid_request400Body 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-05-15 for unauthenticated requests.

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

"2026-05-15"

Path Parameters

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

Response

Updated character

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

​
client_reference_id
object

Caller-supplied reference echoed back (the value sent on create). Null if unset.

Example:

"bot_8472"

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