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: total pixels must be in 3,600,000..16,777,216 and aspect ratio (W/H) in 1/16..16; out-of-bounds values are rejected with `400 validation_error` before any debit. `1K` is no longer accepted — use `2K` or larger. 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. Combine with a preset `size` (`2K` / `4K`) and the server resolves to explicit pixels for you (e.g. `size: "2K"` + `aspectRatio: "landscape"` → `2560x1440`). `auto` (default) lets the model pick. 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. Constraint: references.length + n ≤ 15. 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. "url" gives signed CDN URLs valid for 23 hours. "b64_json" returns base64 inline (large payloads).

Set to "auto" to generate a connected series of images where the same subject is preserved across frames (storyboards, life stages, brand-visual sets). Use together with `sequentialOptions.maxImages`. Do NOT combine with `n > 1`.

Number of frames in the connected series. 1–15.

Example: 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. After 23 h the image is no longer accessible — long-term storage will be available on a paid plan in the future. Save a copy on your side 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).