xSD 5 Pro

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 `xSD5Pro` to use this model. See the list of currently available aliases in the docs.

Example: "xSD5Pro"

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. Preset `1K` or `2K` (this model does not support `4K`), or explicit pixels (e.g. `1440x2560` for a tall 9:16). Defaults to `2K`. For this model explicit-pixel values must have total pixels in 921,600..4,624,220 and aspect ratio (W/H) in 1/16..16; out-of-bounds values are rejected with `400 validation_error` before any debit. Billing is size-based (`1K` and `2K` bill at different per-image rates); explicit sizes bill by resolution tier (below 2,500,000 total pixels bills as `1K`, otherwise as `2K`). Combine with `aspectRatio` to pick a specific aspect under a preset (e.g. `size: "2K"`, `aspectRatio: "landscape"`). When `size` is explicit `WxH`, any `aspectRatio` is ignored (explicit `size` wins).

Example: "2K"

Convenience selector for aspect ratio: `square` (1:1), `landscape` (16:9), `portrait` (3:4). Combine with a preset `size` (`1K` / `2K`) and the server resolves to explicit pixels for you (e.g. `size: "2K"` + `aspectRatio: "landscape"` → `2560x1440`, `+ "portrait"` → `1728x2304`). `auto` (default) lets the model pick. For other ratios (e.g. tall 9:16) pass an explicit `WxH` size instead (e.g. `1440x2560`).

Example: "landscape"

How many images to generate in this single request. 1–15. Constraint: references.length + n ≤ 15. Each image is billed at the size-based rate.

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 (size-based); 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).