xSD 4.5

REQUIRED. Email of YOUR real end-user inside your product — the person who actually triggered this generation. We use it to attribute every request and give you a chain of responsibility: you can list, audit, and delete that user's generations. Do NOT pass a fake address, a shared placeholder, or someone else's email — that's a policy violation. If an end-user generates disallowed content and you do not act, your account can be suspended (see Acceptable use).

Example: "alice@your-product.com"

English text prompt describing the image. Best results follow the structure: subject + action + environment, then style + lighting + composition. For text inside the image, use double quotes (Poster with the title "Hello").

Example: "Editorial photo of a woman in a cobalt-blue silk gown on a rainy Tokyo street at night"

Public model alias. Required — pass the alias of the model you want to use (e.g. xSD4.5). See the list of currently available aliases below.

Example: "xSD4.5"

Reference image(s) used for face/style/character consistency. Single HTTPS URL or array of 1–10 URLs. When using multiple references, name them in the prompt (e.g. "use image_1 for the face, image_2 for the outfit") so the model knows what to copy from each.

Example: "https://example.com/face.jpg" or ["https://example.com/face.jpg", "https://example.com/outfit.jpg"]

Output dimensions. Either a preset (`2K`, `4K` — model picks aspect ratio when used alone) or explicit pixels (e.g. `2048x2048`, `1664x2496`, `2560x1440`). Explicit-pixel values are validated up front: for this model total pixels must be in 3,686,400..16,777,216 (i.e. between 2560×1440 and 4096×4096 worth of pixels, in any shape) and aspect ratio (W/H) in 1/16..16; out-of-bounds values are rejected with `400 validation_error` before any debit. `1K` is not accepted — use `2K` or larger. This model bills a flat rate per image, so a `4K` output costs the same as a `2K` one. Combine with `aspectRatio` to pick a specific aspect under a preset. When `size` is explicit `WxH`, any `aspectRatio` is ignored (explicit `size` wins).

Example: "2048x2048"

Convenience selector for aspect ratio: `square` (1:1), `landscape` (16:9), `portrait` (3:4). Combine with a preset `size` (`2K` / `4K`) and the server resolves to the dimensions this model is tuned for (e.g. `size: "2K"` + `aspectRatio: "landscape"` → `2848x1600`, `+ "portrait"` → `1728x2304`). The exact pixels are model-specific and are not a fixed contract — they are the bucket this model is tuned for at that tier, and can change; read the delivered size back from `images[].size`, or pass an explicit `WxH` size if you need to pin it. Billing follows the resolution tier, so the exact dimensions never change the price. `auto` (default) lets the model pick. For other ratios (e.g. tall 9:16) pass an explicit `WxH` size instead (e.g. `1440x2560`). Silently ignored when `size` is already explicit `WxH` — explicit `size` always wins, no error is raised.

Example: "landscape"

How many images to generate in this single request. 1–15, independent of how many references you pass — each image is produced separately, so references are not drawn from the same budget here. (The combined `references + images ≤ 15` ceiling applies only to `sequential` mode, where one call carries both.) Each image is billed.

Example: 4

Determinism seed. Same seed + same prompt + same model + same other params = same output. If omitted, the server picks a random seed for you and returns it in `GET /v1/generations/:requestId` (`input.seed`), so any generation can be reproduced after the fact — even when you didn't pass one in.

Example: 42

Whether to add a small platform watermark in the corner.

How strictly the model follows the prompt. Lower = more creative interpretation, higher = stricter rendering. Typical range 5–10.

Example: 7.5

How images are returned. Only "url" is currently supported — signed CDN URLs valid for 23 hours. "b64_json" is reserved and rejected with `400 validation_error` before any debit; download from the returned URL instead.

Set to "auto" to generate a connected series of images where the same subject is preserved across frames (storyboards, life stages, brand-visual sets). Requires `sequentialOptions.maxImages`. Do NOT combine with `n > 1`. Model-specific: only some models support series — asking an unsupported model for one is rejected with `400 validation_error` before you are charged. In "auto" mode the MODEL decides how many frames to return, based on your prompt: if the prompt only describes variety ("different angles"), it will satisfy that inside a single image as a collage. Ask for separate images explicitly — e.g. "a series of 4 SEPARATE images — do not combine them into a grid, collage or sheet".

Required whenever `sequential` is "auto" — the request is rejected without it. `maxImages` is an upper bound on how many images the series may contain, 1–15. This is a ceiling, NOT a guaranteed count — the model returns anywhere from 1 to this many, depending on how explicitly the prompt asks for separate images. Keep it at or above the number of frames your prompt asks for; a lower ceiling than the prompt requests is contradictory and typically comes back as one collage. Constraint: references.length + maxImages ≤ 15. xTokens are reserved for the full ceiling up front and the unused part is refunded automatically once the generation settles.

Example: { "maxImages": 4 }

Optional public HTTPS URL we will POST the final record to once the generation is succeeded or failed. The body is identical to what GET /v1/generations/:requestId returns. Each delivery is HMAC-signed (`X-XMode-Signature: v1=<hex>`) and timestamped (`X-XMode-Timestamp`); reject anything older than 5 minutes. Private/loopback IPs are refused (SSRF guard). See the Webhook delivery section in the Introduction for verification code.

Example: "https://your-app.example.com/hooks/xmode"

Unique id of the generation. Use it with GET /v1/generations/:requestId to poll.

Public alias of the model that will produce the images.

Lifecycle marker. POST always returns `queued`. GET returns the current state. `expired` means the request succeeded more than 23 hours ago and signed URLs no longer work — re-run if you need the images again.

Present on `queued` responses only. Absolute URL to GET for status. Recommended polling cadence: every 5 seconds until terminal.

Present only when status=`succeeded`. Each item has `id`, `expiresAt`, and EITHER `url` (signed, valid 23 h) OR `error: { code: "storage_failed" }` if our storage layer dropped that single image. If every image of the request is dropped there is nothing to deliver, so the request comes back `failed` and refunded instead. The URL is re-signed on every read, so re-reading this record replaces a link that went stale on your side — but that never moves `expiresAt`, which is fixed when the generation completed. Once it passes, the record returns status `expired` with no URL and the bytes are gone. Long-term storage will be available on a paid plan in the future; until then, download inside the window or re-generate.

Present only when status=`failed`. `{ code, message }`. The same code values as the top-level error format (validation_error, content_policy, provider_error, provider_timeout, internal_error).

Present only when status=`succeeded`. `{ xTokens: number }`. Debited at request time; refunded automatically on `failed`.

Present on terminal statuses (`succeeded`, `failed`, `expired`). When the generation reached its final state.

Echoed back so you can confirm the grouping. Always lowercase.

When the request was accepted (POST time).