> ## 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. # Context images > Supply up to 10 loose reference images for multi-image composition, addressed positionally from your prompt — no identity grouping, no identity guarantee. `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[]`](/guides/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_` 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: ```json theme={null} { "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[]`](/guides/subjects) — identity-guaranteed composition | | A single identity input, the pre-`subjects[]` way | Legacy `character_id` / `reference_image_urls` — still supported, see the [migration guide](/guides/subjects#migrating-from-the-legacy-fields) | 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 ```bash theme={null} 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 }' ``` ```json theme={null} { "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](/webhooks)) 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_` 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](#when-an-image-url-cant-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_` 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: ```json theme={null} { "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](#when-an-image-url-cant-be-fetched). `file_` 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](/idempotency). ## Where to next? * [Subjects](/guides/subjects) — identity-guaranteed composition, when the output must be a consistent someone * [Create an image](/api-reference/images/create-image) — full request/response shape * `POST /v1/files` — mint a `file_` to use as an entry (see the API reference) * [Error reference](/errors#mutually_exclusive_input) — the combination errors in detail * [Cost transparency](/guides/cost-transparency) — how the credit receipt works