Composition acts

A composition act (an act, for short) is a ready-made way of arranging your subjects in the frame — a pose or interaction the platform reproduces with the people you supply. Instead of describing the whole arrangement in your prompt, you pin an act by its action_id and let it handle the composition while your prompt handles everything else. This guide covers what an act is, how to browse the catalog at GET /v1/actions, how action_id behaves on POST /v1/images, and how an act is matched to the number of subjects you send.

What a composition act is

Each act in the catalog is a small, self-describing record:

{
  "id": "3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c",
  "name": "Over-the-shoulder",
  "description": "One subject framed from behind another",
  "supported_character_counts": [1, 2],
  "preview_url": "https://api.aurous-labs.com/…signed…"
}

id — the identifier you pass as action_id on POST /v1/images. Treat it as opaque: it comes from GET /v1/actions and nowhere else.
name / description — human-readable labels for building a picker in your own UI.
supported_character_counts — the subject counts this act is built for (see Count matching). Pin the act with a matching number of subjects.
preview_url — a signed preview image URL served by the API (GET /v1/actions/{id}/preview). The image bytes stream through the API, so the URL always points at api.aurous-labs.com — never at a storage host. It is short-lived (about an hour) and re-minted every time you list the catalog, so fetch it fresh rather than storing it. null when the act has no preview image.

The catalog

List every act available to your team:

curl https://api.aurous-labs.com/v1/actions \
  -H "X-Api-Key: $AUROUS_API_KEY"

[
  {
    "id": "3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c",
    "name": "Over-the-shoulder",
    "description": "One subject framed from behind another",
    "supported_character_counts": [1, 2],
    "preview_url": "https://api.aurous-labs.com/…signed…"
  }
]

The response is a flat array — the catalog is small and curated, so there is no pagination. Fetch a single act by id to re-check its liveness and current supported_character_counts (which can change as the act’s reference material is updated):

curl https://api.aurous-labs.com/v1/actions/3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c \
  -H "X-Api-Key: $AUROUS_API_KEY"

An id that is unknown, not currently live, or not visible to your team returns 404 resource_not_found — the same response a nonexistent id would give, so the catalog never reveals which acts exist outside your team.

Pinning an act: the `action_id` tri-state

action_id on POST /v1/images has three distinct states, and the difference between “omitted” and “explicit null” is meaningful:

You send	Behavior
`action_id` omitted	Automatic. The platform may detect and apply a matching act based on your prompt and subjects.
`action_id: null`	Detection off. No act is applied — a plain subjects/prompt generation, even if one would otherwise have matched.
`action_id: "<id>"`	Pinned. Exactly this act is applied. It must be live and visible to your team, and support your subject count.

So omitting the field opts in to automatic detection (the default behavior); sending an explicit null opts out for that one request; sending an id pins a specific act. This mirrors how you might already treat an unset field versus a deliberately-null one — here the distinction is load-bearing, so send the state you mean.

Count matching

An act declares the subject counts it supports in supported_character_counts. When you pin an act and send subjects, the number of subjects must be one of those counts:

Matching count — the act is applied. For example, an act whose supported_character_counts is [1, 2] accepts one or two subjects.
Unsupported count — the request returns 400 action_not_available, and the message names the counts the act does support (e.g. "This act supports 1 or 2 subjects; you sent 3."). Fix the request client-side — drop a subject, or pick a different act — and resubmit.

Sending an act with zero subjects is always valid and skips the count check entirely: the act renders a new person described by your prompt. This is the one case where supported_character_counts does not apply. The count that is matched against supported_character_counts is the number of subject entries — one per element of subjects[], plus the folded legacy character_id / reference_image_urls (each folds into a single entry). Every character subject counts as one, and every reference subject counts as one regardless of how many image_urls it carries — a reference subject with three images is still one subject for count matching. So an act whose supported_character_counts is [1, 2] accepts one or two subject entries, whether those subjects reference one image each or several. This is a different count from the reference-image budget: across all subjects, the total number of reference images (plus the act’s own reference material) must stay within the 10-image limit, or the request returns 400 too_many_reference_images (param is subjects). Count matching is about how many subjects you send; the budget is about how many images they add up to.

Quickstart

Pin an act and compose it with two saved characters:

curl -X POST https://api.aurous-labs.com/v1/images \
  -H "X-Api-Key: $AUROUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "prompt": "Two colleagues at a product launch, warm evening light",
    "action_id": "3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c",
    "subjects": [
      { "type": "character", "character_id": "char_01HXMQ7Z3K8Y2VNABCDEFGHJKM" },
      { "type": "character", "character_id": "char_01HXMQ7Z3K8Y2WNABCDEFGHJKM" }
    ]
  }'

{
  "object": "inference",
  "id": "img_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
  "status": "pending",
  "prompt": "Two colleagues at a product launch, warm evening light",
  "action": { "id": "3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c", "name": "Over-the-shoulder" },
  "subjects": [
    { "type": "character", "character_id": "char_01HXMQ7Z3K8Y2VNABCDEFGHJKM", "image_count": 1 },
    { "type": "character", "character_id": "char_01HXMQ7Z3K8Y2WNABCDEFGHJKM", "image_count": 1 }
  ],
  "image_count": 1,
  "created_at": "2026-07-18T10:00:00Z"
}

Poll GET /v1/images/{id} (or register a webhook endpoint) until status reaches a terminal value, same as any other generation.

Rules

Combination	Result
`action_id` and `lora_id`	400 `parameter_invalid_combination` — an act picks its own model and can’t be paired with a style. `param` is `action_id`.
`action_id` and `context_images`	400 `mutually_exclusive_input` — compose an act with subjects (or nothing), not loose context images. `param` is `action_id`.
`action_id` and `subjects` at a supported count	Allowed — the act is applied.
`action_id` and `subjects` at an unsupported count	400 `action_not_available` — the message names the supported counts. `param` is `action_id`.
`action_id` and zero subjects	Allowed — renders a new person from your prompt (count check skipped).
Unknown / not-live / cross-team `action_id`	404 `resource_not_found` — no existence leak.
`action_id` + subjects that exceed the 10-image budget	400 `too_many_reference_images`. `param` is `subjects`.

action_id: null and an omitted action_id never trigger the combination rules above — they mean “detection off” and “detection on”, not “pin an act.”

The response

Every GET/POST response for a generation — and every webhook delivery, which carries the same shape — now includes an action field:

{
  "action": { "id": "3f2b6c1e-8a4d-4e2b-9c7a-1d5e8f0a2b3c", "name": "Over-the-shoulder" }
}

action echoes the act that was applied — whether you pinned it with action_id or it was detected automatically — as { id, name } and nothing more. It never carries the preview image, the reference material, or any internal selection detail.
action.name may be null when a display name wasn’t recorded for the act, but action.id is always present when an act was applied.
action is null on every generation that didn’t apply an act — plain prompt-only generations, style (lora_id) generations, context-image generations, and all video generations. It’s a new, always-present, nullable key: existing integrations that don’t read it are unaffected.

Retired styles still serve as acts

A single style in GET /v1/loras and a composition act can share the same underlying model. When that model is retired as a style, one thing changes that’s worth calling out:

It disappears from GET /v1/loras — it’s no longer offered as a browsable style, and automatic style matching won’t pick it. This is the one behavior change to be aware of: a style that was previously listed can drop off the list once it’s retired.
Its act stays in GET /v1/actions as long as the act itself is live — the actions catalog is the only place a retired model surfaces publicly.
An explicit lora_id you’ve already persisted for that model keeps working on POST /v1/images — retiring a style hides it from discovery but never breaks a request that names it directly.

The list at GET /v1/loras was never a stability contract, so this isn’t a breaking change — but if you cache the catalog, expect a retired style to vanish from it while everything that references it by id keeps working.

Estimates

POST /v1/images/estimate mirrors the create path: pin an action_id and it runs the identical act gates — the existence/visibility check (unknown → 404 resource_not_found) and, when subjects are present, the count check (unsupported → 400 action_not_available) — without dispatching or charging. Acts don’t change the price (their reference material is free), so an act estimate quotes the standard single-image rate. As with any estimate, inline https:// reference URLs are validated for shape but never fetched — a URL-specific problem only surfaces at create.

Where to next?

Subjects — compose one or more identities into a single image
Context images — loose, prompt-directed references with no identity grouping
Create an image — full request/response shape
action_not_available — the count-mismatch error in the error reference
Cost transparency — how the credit receipt works

Get started

Guides

Concepts

API Reference

Resources

What a composition act is

The catalog

Pinning an act: the `action_id` tri-state

Count matching

Quickstart

Rules

The response

Retired styles still serve as acts

Estimates

Where to next?

​What a composition act is

​The catalog

​Pinning an act: the action_id tri-state

​Count matching

​Quickstart

​Rules

​The response

​Retired styles still serve as acts

​Estimates

​Where to next?

What a composition act is

The catalog

Pinning an act: the `action_id` tri-state

Count matching

Quickstart

Rules

The response

Retired styles still serve as acts

Estimates

Where to next?