Context images

context_images[] is how you hand POST /v1/images a set of loose reference images — up to 10 of them — and direct the composition entirely from your prompt. Unlike subjects[], the images carry no structure: there is no identity grouping, no per-subject framing, and no identity-consistency guarantee. The composition model reads your prompt, looks at the images in the order you sent them, and interprets what to take from each one. This guide covers what the field does, when to reach for it instead of subjects[] or the legacy fields, and what’s different about a generation that uses it.

What `context_images[]` is

A flat, ordered array of image inputs. Each entry is either an opaque file_<ulid> from POST /v1/files or an https:// URL to a public host (max 2048 chars) — the same entry shape reference_image_urls and reference subjects already accept:

{
  "prompt": "The woman in Image 1 wearing the outfit from Image 2, in the setting of Image 3",
  "context_images": [
    "file_01HXMQ7Z3K8Y2NABCDEFGHJKMN",
    "https://example.com/outfit.jpg",
    "https://example.com/venue.jpg"
  ],
  "enhance_prompt": true
}

The array is positional: entry 1 is “Image 1”, entry 2 is “Image 2”, and so on, up to “Image 10”. Your prompt addresses them by that position — “the outfit from Image 2”, “the setting of Image 3”. Reordering the array changes which image each position refers to, so keep prompt and array in sync. Omit context_images entirely, or send [], and the request is a plain generation — both are treated as “no context images.”

When to use it

You want	Use
Loose, prompt-directed composition — “take the pose from this, the palette from that” — with no identity guarantee	`context_images[]` (this guide)
One or more identities composed with consistency — saved characters, or reference sets that should read as the same person	`subjects[]` — identity-guaranteed composition
A single identity input, the pre-`subjects[]` way	Legacy `character_id` / `reference_image_urls` — still supported, see the migration guide

The rule of thumb: if the output must be someone — same face across renders — use subjects[] or a saved character. If the images are raw material for the prompt to draw on, use context_images[].

Quickstart

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": "The woman in Image 1 wearing the outfit from Image 2, in the setting of Image 3",
    "context_images": [
      "file_01HXMQ7Z3K8Y2NABCDEFGHJKMN",
      "https://example.com/outfit.jpg",
      "https://example.com/venue.jpg"
    ],
    "enhance_prompt": true
  }'

{
  "object": "inference",
  "id": "img_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
  "status": "pending",
  "media_type": "image",
  "prompt": "The woman in Image 1 wearing the outfit from Image 2, in the setting of Image 3",
  "context_images": { "image_count": 3 },
  "subjects": null,
  "image_count": 1,
  "seed": null,
  "negative_prompt": null,
  "cost": {
    "amount": 2.0,
    "currency": "credit",
    "breakdown": { "base": 1.0, "enhance": 1.0 }
  },
  "created_at": "2026-07-16T10:00:00Z"
}

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

Rules

context_images[] is one of three mutually exclusive input styles — pick exactly one per request:

Combination	Result
`context_images[]` and `subjects[]`, `character_id`, or `reference_image_urls`	400 `mutually_exclusive_input` — one input style per request. `param` is `context_images`.
`context_images[]` and `lora_id`	400 `parameter_invalid_combination` — multi-image composition picks its own model; a style can’t be stacked on top. `param` is `context_images`.
11 or more entries	400 `value_out_of_range` — the array is capped at 10. `param` is `context_images`.
An `http://` entry, or a URL resolving to a private host	400 `invalid_format` — entries must be `file_<ulid>` IDs or `https://` URLs to public hosts. `param` is `context_images`.
A well-formed `https://` entry that can’t be fetched at create time	400 `invalid_format` — see When an image URL can’t be fetched. `param` is `context_images`.

The 10-image budget

The cap is a flat 10 entries — every entry contributes exactly one input image, so unlike subjects[] there is no per-entry arithmetic to do. Go over it and the request returns 400 value_out_of_range; the endpoint does not trim on your behalf. Fix the request client-side (drop an entry) and resubmit.

When an image URL can’t be fetched

Entries are validated for shape at request time — both POST /v1/images/estimate and POST /v1/images reject an http:// entry or a private-host URL up front. The actual fetch of an https:// entry happens only at create: a URL that is well-formed but unreachable, returns a non-success status, redirects, or doesn’t resolve to a valid image comes back as 400 invalid_format from POST /v1/images. The estimate never fetches, so it won’t catch this — a request that estimates cleanly can still 400 at create if one of its URLs is down. To stay clear of it, make sure every https:// entry is publicly reachable and points directly at the image bytes — not at an HTML page that displays the image. Or sidestep fetching entirely: upload the image via POST /v1/files and pass the file_<ulid> instead. File entries are fetched and validated at upload time, so they can’t fail this way at create.

The response

Every GET/POST response for a generation — and every webhook delivery — carries a context_images field:

{
  "context_images": { "image_count": 3 },
  "subjects": null
}

The echo is a count only — the number of entries you sent. The image URLs themselves are never echoed back, on any response shape.
subjects is always null on a context-image generation — the two projections never appear together.
context_images is null on every generation that didn’t use it — plain prompt-only, style, subject, and video generations. It’s a new, always-present, nullable key: existing integrations that don’t read it are unaffected.

What’s different about a context-image generation

A generation that uses context_images[] always runs on the multi-image composition pipeline. A few things follow:

Exactly one output image. count is accepted but ignored — you always get one image back, priced at the standard single-image rate with no per-image surcharge for the references you attach.
Tuning knobs are inert. steps, guidance_scale, cfg_rescale, denoise_strength, negative_prompt, and seed are accepted without error, but the composition pipeline uses optimized settings and doesn’t apply them. On the response, cfg_rescale and denoise_strength are omitted, and seed and negative_prompt come back null, regardless of what you sent.
output_format: "png" for transparency. The default is jpeg. Set output_format: "png" if you want a transparent background where the composition supports it.

Estimates

POST /v1/images/estimate mirrors all of the above: a context_images[] estimate always quotes exactly one image (count is ignored, matching create) and fires the same 400 combination errors a real POST /v1/images would. The estimate never fetches your inline https:// entries — their shape is validated, but a problem specific to a URL (unreachable host, non-image content) only surfaces at create, as 400 invalid_format — see When an image URL can’t be fetched. file_<ulid> entries are still ownership-checked.

Idempotency

The order of context_images[] is part of the request body, so reusing an Idempotency-Key with the same entries in a different order is a different request — it returns 409 idempotency_key_in_use, not a replay. And as always, only successful responses are cached for replay: a request that 400s on one of the combination rules above is never cached, so you can fix the body and retry under the same key. See Idempotency.

Where to next?

Subjects — identity-guaranteed composition, when the output must be a consistent someone
Create an image — full request/response shape
POST /v1/files — mint a file_<ulid> to use as an entry (see the API reference)
Error reference — the combination errors in detail
Cost transparency — how the credit receipt works

Get started

Guides

Concepts

API Reference

Resources

What `context_images[]` is

When to use it

Quickstart

Rules

The 10-image budget

When an image URL can’t be fetched

The response

What’s different about a context-image generation

Estimates

Idempotency

Where to next?

​What context_images[] is

​When to use it

​Quickstart

​Rules

​The 10-image budget

​When an image URL can’t be fetched

​The response

​What’s different about a context-image generation

​Estimates

​Idempotency

​Where to next?

What `context_images[]` is

When to use it

Quickstart

Rules

The 10-image budget

When an image URL can’t be fetched

The response

What’s different about a context-image generation

Estimates

Idempotency

Where to next?