List the eight named character views
curl --request GET \
--url https://api.aurous-labs.com/v1/characters/views \
--header 'X-Api-Key: <api-key>'import requests
url = "https://api.aurous-labs.com/v1/characters/views"
headers = {"X-Api-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-Api-Key': '<api-key>'}};
fetch('https://api.aurous-labs.com/v1/characters/views', 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/views",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"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"
"net/http"
"io"
)
func main() {
url := "https://api.aurous-labs.com/v1/characters/views"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Api-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.aurous-labs.com/v1/characters/views")
.header("X-Api-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.aurous-labs.com/v1/characters/views")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Api-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"object": "character_view_catalog",
"views": [
{
"view": "head_front",
"part": "head",
"label": "Head — front",
"description": "Head and shoulders, facing the camera.",
"order": 0
}
],
"constraints": {
"min_short_side_px": 512,
"max_aspect_ratio": 2.5,
"max_dimension_px": 4096,
"content_types": [
"image/jpeg",
"image/png",
"image/webp"
]
}
}{
"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",
"reason": "wrong_view",
"detected_view": "full_left"
}
}{
"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",
"reason": "wrong_view",
"detected_view": "full_left"
}
}{
"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",
"reason": "wrong_view",
"detected_view": "full_left"
}
}{
"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",
"reason": "wrong_view",
"detected_view": "full_left"
}
}Characters
List character views
The eight named views a character can be composed of, with the local pre-check constraints for reference uploads.
GET
/
v1
/
characters
/
views
List the eight named character views
curl --request GET \
--url https://api.aurous-labs.com/v1/characters/views \
--header 'X-Api-Key: <api-key>'import requests
url = "https://api.aurous-labs.com/v1/characters/views"
headers = {"X-Api-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-Api-Key': '<api-key>'}};
fetch('https://api.aurous-labs.com/v1/characters/views', 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/views",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"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"
"net/http"
"io"
)
func main() {
url := "https://api.aurous-labs.com/v1/characters/views"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Api-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.aurous-labs.com/v1/characters/views")
.header("X-Api-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.aurous-labs.com/v1/characters/views")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Api-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"object": "character_view_catalog",
"views": [
{
"view": "head_front",
"part": "head",
"label": "Head — front",
"description": "Head and shoulders, facing the camera.",
"order": 0
}
],
"constraints": {
"min_short_side_px": 512,
"max_aspect_ratio": 2.5,
"max_dimension_px": 4096,
"content_types": [
"image/jpeg",
"image/png",
"image/webp"
]
}
}{
"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",
"reason": "wrong_view",
"detected_view": "full_left"
}
}{
"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",
"reason": "wrong_view",
"detected_view": "full_left"
}
}{
"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",
"reason": "wrong_view",
"detected_view": "full_left"
}
}{
"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",
"reason": "wrong_view",
"detected_view": "full_left"
}
}Every character is composed of up to eight named views, grouped by body part.
The table is in canonical order — the order
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.
| Part | View | What the photo shows |
|---|---|---|
| Head | head_front | Head and shoulders, facing the camera — the face every generation copies |
| Upper body | upper_front | Chest to hips, facing the camera |
| Lower body | lower_front | Hips through legs, facing the camera |
| Upper body | upper_back | Rear upper body, head to waist |
| Lower body | lower_back | Rear lower body, waist through legs |
| Full body | full_left | Standing, head to feet, strict left profile |
| Full body | full_front | Standing, head to feet, facing the camera |
| Full body | full_right | Standing, head to feet, strict right profile |
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 byorder, label fromlabel. - You want to reject an unusable photo locally, before spending a round-trip: check
constraintsclient-side. These are exactly the valuesPUT /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
curl https://api.aurous-labs.com/v1/characters/views \
-H "X-Api-Key: $AUROUS_API_KEY"
const catalog = await fetch("https://api.aurous-labs.com/v1/characters/views", {
headers: { "X-Api-Key": process.env.AUROUS_API_KEY! },
}).then((r) => r.json());
console.log(catalog.views.map((v) => v.view)); // ["head_front", ...]
import os, requests
catalog = requests.get(
"https://api.aurous-labs.com/v1/characters/views",
headers={"X-Api-Key": os.environ["AUROUS_API_KEY"]},
).json()
print([v["view"] for v in catalog["views"]])
Response
views[]— exactly eight{ view, part, label, description, order }entries in canonical order.partis one ofhead,upper_body,lower_body,full_body; group by it in your UI.orderis 0–7 and matches the order references come back in.constraints—min_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.
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 liveX-RateLimit-Limitheader reports the burst, so it reads240). The catalogue is static; cache it. - No price is returned here. Read
build.per_view_creditson any character.
Errors
| Code | HTTP | When |
|---|---|---|
invalid_api_key | 401 | Missing, malformed, or revoked X-Api-Key. |
insufficient_scope | 403 | The key does not carry the read scope. |
too_many_requests | 429 | Sustained > 120/min. |
provider_unavailable | 503 | The platform could not serve the request; retry after Retry-After seconds. |
Common pitfalls
- Don’t assume a character has every view in this list. Read
views[]on the character for what it actually has, andbuild.missing_viewsfor what a build would add. - The catalogue carries no price and no
requiredflag.build.per_view_creditson a character is the only price. orderis 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 whosestatusismissing.
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"

