> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aurous-labs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List character views
> The eight named views a character can be composed of, with the local pre-check constraints for reference uploads.
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.
| 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 |
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](/api-reference/characters/regenerate-view), which adds a view the character does not have; `full_front` is also reachable through the deprecated body form ([Regenerate a ref pose](/api-reference/characters/regenerate-ref) 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](/api-reference/characters/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}`](/api-reference/characters/put-ref) 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
```bash cURL theme={null}
curl https://api.aurous-labs.com/v1/characters/views \
-H "X-Api-Key: $AUROUS_API_KEY"
```
```typescript Node.js theme={null}
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", ...]
```
```python Python theme={null}
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. `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.
* `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.
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`](/api-reference/characters/regenerate-view); 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
| 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, 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`.
## OpenAPI
````yaml GET /v1/characters/views
openapi: 3.0.0
info:
title: Aurous Labs API
description: >-
Generate AI images with custom LoRA styles.
## Authentication
All requests require an API key passed in the `X-Api-Key` header.
Create API keys in your
[dashboard](https://app.aurous-labs.com/dashboard/api-keys).
## Closed-beta access gate
API keys are scoped to a user. If that user's account is not approved for
the closed beta, every request returns `403` with one of these `error.code`
values:
- `account_pending` — awaiting review
- `account_rejected` — declined post-signup
- `account_suspended` — was approved, then suspended
There is no retry — contact support to be approved. The same codes are
emitted by the WebSocket gateway via 4001 close.
## Common headers
Every response carries `Aurous-Request-Id` (a server-minted `req_` for
support tracing) and `Aurous-Version` (the API version applied to the
response). Optionally pin a version on the request with `Aurous-Version:
YYYY-MM-DD` — omit it and the platform default applies (currently
`2026-08-26`).
## Quick Start
```bash
curl -X POST https://api.aurous-labs.com/v1/images \
-H "X-Api-Key: al_live_your_key" \
-H "Content-Type: application/json" \
-d '{"prompt": "A golden sunset over mountains", "lora_id": "your-lora-id", "size": "1_5k_1_1"}'
```
version: 1.0.0
contact: {}
servers:
- url: https://api.aurous-labs.com
description: Production
- url: https://api.preprod.aurous-labs.com
description: Preprod (staging)
security: []
tags:
- name: Seedance (raw)
description: >-
Drop-in raw passthrough for Seedance video generation. Point the official
Seedance provider SDK at this API's base URL and authenticate with your
Aurous API key in the `X-Api-Key` header — request bodies are forwarded to
the provider verbatim and responses come back shape-identical, so you keep
the provider's exact request/response shapes. Task ids are Aurous-native
`vid_…` ids. Billing rides response headers, not the body:
`Aurous-Credits-Held` on the create response and `Aurous-Credits-Charged`
on a settled, succeeded task read — the body itself stays provider-shaped.
paths:
/v1/characters/views:
get:
tags:
- Public API (v1) — Characters
summary: List the eight named character views
description: >-
The closed list of views a character is composed of, grouped by body
part, with the local pre-check constraints for reference uploads
(content types, minimum short side, maximum aspect ratio, maximum
dimension). Static; cache it. Prices are not here — read
`build.per_view_credits` on a character.
operationId: V1CharactersController_views
parameters:
- name: Aurous-Version
in: header
required: false
description: >-
Optional API version pin (YYYY-MM-DD). Omit the header to receive
the platform default, currently `2026-08-26`.
schema:
type: string
example: '2026-08-26'
pattern: ^\d{4}-\d{2}-\d{2}$
responses:
'200':
description: The view catalogue
content:
application/json:
schema:
$ref: '#/components/schemas/CharacterViewCatalog'
headers:
Aurous-Request-Id:
description: Server-minted request id. Quote this in support tickets.
schema:
type: string
example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP
Aurous-Version:
description: API version pin applied to this response (YYYY-MM-DD).
schema:
type: string
example: '2026-08-26'
X-RateLimit-Limit:
description: Bucket capacity (max tokens) for this endpoint class.
schema:
type: integer
example: 120
X-RateLimit-Remaining:
description: Tokens remaining after this request.
schema:
type: integer
example: 119
X-RateLimit-Reset:
description: >-
Epoch seconds when the bucket would be full again, assuming no
further requests.
schema:
type: integer
example: 1700000060
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
headers:
Aurous-Request-Id:
description: Server-minted request id. Quote this in support tickets.
schema:
type: string
example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP
Aurous-Version:
description: API version pin applied to this response (YYYY-MM-DD).
schema:
type: string
example: '2026-08-26'
X-RateLimit-Limit:
description: Bucket capacity (max tokens) for this endpoint class.
schema:
type: integer
example: 120
X-RateLimit-Remaining:
description: Tokens remaining after this request.
schema:
type: integer
example: 119
X-RateLimit-Reset:
description: >-
Epoch seconds when the bucket would be full again, assuming no
further requests.
schema:
type: integer
example: 1700000060
'403':
description: >-
Account not approved for closed beta. error.code is one of
`account_pending`, `account_rejected`, `account_suspended`. There is
no retry — contact support to be approved.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
headers:
Aurous-Request-Id:
description: Server-minted request id. Quote this in support tickets.
schema:
type: string
example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP
Aurous-Version:
description: API version pin applied to this response (YYYY-MM-DD).
schema:
type: string
example: '2026-08-26'
X-RateLimit-Limit:
description: Bucket capacity (max tokens) for this endpoint class.
schema:
type: integer
example: 120
X-RateLimit-Remaining:
description: Tokens remaining after this request.
schema:
type: integer
example: 119
X-RateLimit-Reset:
description: >-
Epoch seconds when the bucket would be full again, assuming no
further requests.
schema:
type: integer
example: 1700000060
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
headers:
Aurous-Request-Id:
description: Server-minted request id. Quote this in support tickets.
schema:
type: string
example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP
Aurous-Version:
description: API version pin applied to this response (YYYY-MM-DD).
schema:
type: string
example: '2026-08-26'
X-RateLimit-Limit:
description: Bucket capacity (max tokens) for this endpoint class.
schema:
type: integer
example: 120
X-RateLimit-Remaining:
description: Tokens remaining after this request.
schema:
type: integer
example: 119
X-RateLimit-Reset:
description: >-
Epoch seconds when the bucket would be full again, assuming no
further requests.
schema:
type: integer
example: 1700000060
Retry-After:
description: >-
Seconds to wait before retrying. Present on 429 (rate limit), on
503 provider_unavailable, and on 409 character_busy. Prefer this
over computing X-RateLimit-Reset − now.
schema:
type: integer
example: 12
'503':
description: >-
Character generation is temporarily unavailable, or the platform
could not verify your account/billing state or prepare the request
(for example, reference images) before dispatch — error.code is
`provider_unavailable` in every case. Retry after the number of
seconds in the `Retry-After` header.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
headers:
Aurous-Request-Id:
description: Server-minted request id. Quote this in support tickets.
schema:
type: string
example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP
Aurous-Version:
description: API version pin applied to this response (YYYY-MM-DD).
schema:
type: string
example: '2026-08-26'
X-RateLimit-Limit:
description: Bucket capacity (max tokens) for this endpoint class.
schema:
type: integer
example: 120
X-RateLimit-Remaining:
description: Tokens remaining after this request.
schema:
type: integer
example: 119
X-RateLimit-Reset:
description: >-
Epoch seconds when the bucket would be full again, assuming no
further requests.
schema:
type: integer
example: 1700000060
Retry-After:
description: >-
Seconds to wait before retrying. Present on 429 (rate limit), on
503 provider_unavailable, and on 409 character_busy. Prefer this
over computing X-RateLimit-Reset − now.
schema:
type: integer
example: 12
security:
- api-key: []
components:
schemas:
CharacterViewCatalog:
type: object
properties:
object:
type: string
enum:
- character_view_catalog
example: character_view_catalog
views:
description: Exactly eight entries, in canonical view order.
type: array
items:
$ref: '#/components/schemas/CharacterViewCatalogEntry'
constraints:
$ref: '#/components/schemas/CharacterViewConstraints'
required:
- object
- views
- constraints
ErrorResponse:
type: object
properties:
error:
description: Error payload
allOf:
- $ref: '#/components/schemas/ErrorPayload'
required:
- error
CharacterViewCatalogEntry:
type: object
properties:
view:
type: string
enum:
- head_front
- upper_front
- lower_front
- upper_back
- lower_back
- full_left
- full_front
- full_right
example: head_front
part:
type: string
enum:
- head
- upper_body
- lower_body
- full_body
example: head
label:
type: string
example: Head — front
description:
type: string
example: Head and shoulders, facing the camera.
order:
type: number
description: 0–7, the order references are returned in.
example: 0
required:
- view
- part
- label
- description
- order
CharacterViewConstraints:
type: object
properties:
min_short_side_px:
type: number
description: The shorter side of the image must be at least this many pixels.
example: 512
max_aspect_ratio:
type: number
description: >-
Longer side divided by shorter side must not exceed this value.
Inclusive.
example: 2.5
max_dimension_px:
type: number
description: Neither side of the image may exceed this many pixels.
example: 4096
content_types:
description: Accepted MIME types.
example:
- image/jpeg
- image/png
- image/webp
type: array
items:
type: string
required:
- min_short_side_px
- max_aspect_ratio
- max_dimension_px
- content_types
ErrorPayload:
type: object
properties:
type:
type: string
description: Broad error category
example: invalid_request
enum:
- invalid_request
- authentication
- not_found
- rate_limit
- server_error
code:
type: string
description: >-
Stable error code (programmatic discriminator). Closed-beta gate
emits one of `account_pending`, `account_rejected`,
`account_suspended` on 403.
example: balance_too_low
enum:
- invalid_request
- missing_field
- invalid_format
- value_out_of_range
- unsupported_lora_for_mode
- generation_not_cancellable
- prompt_blocked
- reference_blocked
- output_moderation_rejected
- unknown_version
- mutually_exclusive_input
- character_not_ready
- parameter_invalid_combination
- character_status_invalid
- character_busy
- nudity_not_allowed
- reference_unfit
- reference_uploaded
- build_requires_identity
- style_retired
- parameter_invalid
- too_many_reference_images
- action_not_available
- upload_invalid
- balance_too_low
- idempotency_key_in_use
- api_key_not_found
- payload_too_large
- missing_api_key
- invalid_api_key
- revoked_api_key
- resource_not_found
- forbidden_resource
- account_pending
- account_rejected
- account_suspended
- already_approved
- already_rejected
- already_suspended
- invalid_reinstate_target
- invalid_suspend_target
- cannot_moderate_admin
- too_many_requests
- concurrency_limit_exceeded
- tpm_rate_limit_exceeded
- internal_error
- provider_unavailable
- reference_check_unavailable
- provider_timeout
- provider_not_configured
- invalid_time_range
- invalid_bucket_width
- too_many_buckets
- too_many_group_by
- invalid_filter
- invalid_page_token
- export_too_large
- user_already_exists
- self_invite_forbidden
- invite_link_failed
- invite_rate_limited
- model_not_found
- model_disabled
- model_wrong_kind
- max_tokens_exceeds_hard_cap
- chat_model_misconfigured
- embeddings_input_too_large
- embeddings_unsupported_dimensions
- pricing_frozen
- provider_rate_limited
- chat_provider_request_invalid
- chat_provider_auth_failed
- chat_provider_unavailable
- max_input_tokens_exceeded
- chat_provider_unknown_error
- embeddings_provider_unknown_error
- embeddings_batch_not_supported
- embeddings_input_too_many_items
- embeddings_video_unsupported
- encoding_format_unsupported
- missing_max_tokens_no_model_default
- chat_cancel_target_not_found
- chat_completion_not_found
- chat_cancel_target_already_terminal
- chat_cancel_target_not_cancellable
- tool_choice_required_unsupported
- response_format_too_large
- response_format_too_deep
- invalid_cursor
- invalid_cursor_for_endpoint
- model_slug_exists
- output_expired
- output_not_available
- content_filtered
- image_generation_failed
- reference_media_invalid
- reference_media_cap_reached
- reference_fetch_failed
- unsupported_auth_method
- insufficient_scope
- uploads_expired
- character_resynthesize_in_progress
- provider_unknown_error
- first_frame_too_small
message:
type: string
description: Human-readable message
example: Team available balance is 1.5 credits, generation requires 2.0.
param:
type: object
description: Field name when the error is parameter-scoped
example: prompt
nullable: true
reason:
type: string
description: >-
Sub-code refining `code`, for codes that document one. Present today
only on `reference_unfit`; `null` otherwise. Branch on `code` first
and treat an unrecognized `reason` as a generic failure of that
code.
enum:
- too_small
- extreme_aspect
- no_person
- multiple_people
- no_face
- wrong_view
- nudity_mismatch
nullable: true
example: wrong_view
detected_view:
type: string
description: >-
Present only on `reference_unfit` with `reason: "wrong_view"`: the
view the rejected image actually depicts. Offer the customer that
view instead of asking for a new photo — the same upload can be
re-sent to it.
enum:
- head_front
- upper_front
- lower_front
- upper_back
- lower_back
- full_left
- full_front
- full_right
- other
nullable: true
example: full_left
doc_url:
type: string
description: Documentation link for this error code
example: https://docs.aurous-labs.com/errors#balance_too_low
request_id:
type: string
description: Echoes Aurous-Request-Id — quote in support tickets
example: req_01HXMQ7Z3K8Y2VNABCDEFGHJKM
required:
- type
- code
- message
- doc_url
- request_id
securitySchemes:
api-key:
type: apiKey
in: header
name: X-Api-Key
description: Your team API key (starts with `al_live_`).
````