Skip to main content
GET
Retrieve a character
GET /v1/characters/{id} returns a single character. Use it to:
  • Poll a newly created character until status transitions from synthesizing to ready (or failed). Both create flows advance to ready on their own — there is no save step.
  • Read the refs[] array for proxy URLs you can render in your UI.
  • Inspect attributes for the typed identity fields the platform stored.

Status lifecycle

views[] is the canonical read model for what a character actually has, build for what a render would add and cost. Both are explained in Views and lifecycle. Soft-deleted characters return 404 resource_not_found on this endpoint — the V1 surface treats them as gone for IDOR safety. If you need to confirm a soft-delete landed, the 404 itself is the confirmation.

Examples

Limits

  • Rate limit: bucket characters_get — 120 requests/min sustained, 240 burst per team.

Errors

Common pitfalls

  • refs[].url is a proxy URL — do not assume it points at any specific storage host. Treat it as opaque and re-fetch as needed; URLs are valid for ~24h.
  • Polling at 2-second intervals is plenty for synthesize. Tighter polling only burns rate-limit budget.
  • Soft-deleted characters return 404 on this endpoint — if you want to keep an audit trail of past characters, mirror them in your own database before calling DELETE.
  • A draft is a real character with a real id, but it is not usable: attaching it to POST /v1/images or POST /v1/videos returns 400 character_not_ready. Treat anything other than ready as not-yet-usable.
These changes ship on the existing 2026-08-26 contract. No Aurous-Version pin isolates them: the version catalogue carries image and video pricing pointers only, not character pricing or the size of the reference set. Pinning an earlier Aurous-Version restores neither the smaller reference set nor the previous price. A character created before 2026-09-14 keeps the references it already has — add either of the two newer views on demand with POST /v1/characters/{id}/refs/{view}/regenerate; every character created on or after that date carries eight.

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

id
string
required

Opaque character ID

Example:

"char_01HXMQ7Z3K8Y2NABCDEFGHJKMR"

Response

Character details

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

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

build
object
required

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

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.

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"