Skip to main content
DELETE
Remove a view from a draft
DELETE /v1/characters/{id}/refs/{view} empties one of the eight named views on a draft, so the next POST /v1/characters/{id}/build renders that view instead of keeping the photo you filed. The response is the full character with the updated views[] and a recalculated build — the emptied view is back in build.missing_views, and build.cost_credits has gone up by one view’s price. Drafts only. Any other status returns 400 character_status_invalid with param: character_id — replace the view with a new upload instead of removing it. Never charges, and idempotent: a view that holds no reference returns 200 with the character unchanged.

When to use

  • You filed the wrong photo into a view and would rather the platform render it.
  • You want to shrink an assembled draft back toward “let the platform do it” before building.
To replace a view rather than empty it, PUT a new photo into it — see Put a photo into a view. That works on draft, failed, reviewing and ready alike.

Examples

Path parameters

There is no request body.

Removal is draft-only

So a character whose build failed can have a view replaced (PUT) but not removed, until the next successful build. Nothing was lost: the references you uploaded are stored on the character, not as expiring upload tickets, and POST /v1/characters/{id}/build accepts failed precisely so a retry needs no re-upload.

Limits

  • Cost: free. Removing a view renders nothing and charges nothing; it raises what the next build will cost, because there is one more view to render.
  • Rate limit: bucket characters_post — 30 requests/min sustained, 60 burst per team. Shared with the other cheap character writes (draft create, uploads init/classify, PATCH, DELETE /v1/characters/{id}, save).
  • Idempotency: no Idempotency-Key is needed. The operation is naturally idempotent — removing an already-empty view is a 200 with the character unchanged.

Errors

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.

Common pitfalls

  • This removes a view, not the character. To delete the character itself use DELETE /v1/characters/{id}, which hard-deletes a draft.
  • Removing a view raises build.cost_credits — you have given the platform one more view to render. Re-read build after every change rather than caching a quote.
  • The 200 on an already-empty view is deliberate, so a retry after a dropped connection is safe. Don’t treat it as “the view existed”.
  • Removing the view your cover pointed at clears the cover; the head view is the default cover when none is set.

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"

view
enum<string>
required

The view to empty

Available options:
head_front,
upper_front,
lower_front,
upper_back,
lower_back,
full_left,
full_front,
full_right

Response

View emptied (or already empty); updated character returned

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"