Skip to main content
GET
List the eight named character views
Every character is composed of up to eight named views, grouped by body part. GET /v1/characters/views returns that list so your integration never hardcodes it, plus the constraints a reference photo must meet before the platform will look at it. The table is in canonical order — the order views[] comes back in, and the order references are returned in on a character. Every character created on or after 2026-09-14 carries all eight of these views. Characters created before that date carry six — head_front, upper_front, lower_front, upper_back, lower_back, full_left — and gain full_front or full_right on demand through Regenerate a view, which adds a view the character does not have; full_front is also reachable through the deprecated body form (Regenerate a ref pose with { "pose": "front" }). Every character read exposes views[] (one entry per view, with its status — a view the character lacks is missing, never absent) and build (what a render would produce and cost right now). For what those slot states mean, how a slot moves between them, which operation each character status allows, and why a photo you upload can be refused, see Views and lifecycle — the concept page every character endpoint refers back to.

When to use

  • You render a reference grid or an upload UI: group by part, sort by order, label from label.
  • You want to reject an unusable photo locally, before spending a round-trip: check constraints client-side. These are exactly the values PUT /v1/characters/{id}/refs/{view} enforces on the bytes you send.
  • Anywhere you would otherwise hardcode the view names. Fetch once, cache it, and re-read after a deploy.

Examples

Response

  • views[] — exactly eight { view, part, label, description, order } entries in canonical order. part is one of head, upper_body, lower_body, full_body; group by it in your UI. order is 0–7 and matches the order references come back in.
  • constraintsmin_short_side_px (512), max_aspect_ratio (2.5), max_dimension_px (4096), content_types (image/jpeg, image/png, image/webp). Check these locally before uploading a reference; the platform enforces the same values.
There is no required flag on a view and no price in the catalogue — read build.per_view_credits on any character. The response is static per deploy and served with Cache-Control: public, max-age=3600.
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.

Limits

  • Rate limit: bucket characters_get — 120 requests/min sustained, burst 240 per team (the live X-RateLimit-Limit header reports the burst, so it reads 240). The catalogue is static; cache it.
  • No price is returned here. Read build.per_view_credits on any character.

Errors

Common pitfalls

  • Don’t assume a character has every view in this list. Read views[] on the character for what it actually has, and build.missing_views for what a build would add.
  • The catalogue carries no price and no required flag. build.per_view_credits on a character is the only price.
  • order is the catalogue’s canonical order, not a per-character index — views[] on a character always returns all eight entries in this same order, including the ones whose status is missing.

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"

Response

The view catalogue

object
enum<string>
required
Available options:
character_view_catalog
Example:

"character_view_catalog"

views
object[]
required

Exactly eight entries, in canonical view order.

constraints
object
required