xQI 3 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"

Public model alias. Required — pass `xQI3Pro` to use this model. See the list of currently available aliases in the docs.

Example: "xQI3Pro"

Text prompt describing the image. This model rewards detail: subject and action first, then environment, then style, lighting and composition — a paragraph works better than a phrase. Text that must appear inside the image goes in double quotes. When you pass input images, refer to them positionally ("the woman from image 1").

Example: "A vertical portrait of a woman in a black slip dress on a sunlit Rome street, a blue sign reading \"Il Messaggero\" overhead, warm film tones"

Input image(s) to edit or draw from — a single HTTPS URL or an array of 1–3. Passing any switches the request to image editing; there is no separate endpoint or flag. Order is meaningful, so name them positionally in the prompt. Each image must be JPG, JPEG, PNG, BMP, TIFF, WEBP or GIF, at most 10 MB, and works best with both sides between 384 and 2048 px.

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

Output dimensions: preset `1K`, `1.5K` or `2K` (this model has no `4K`), or explicit pixels (e.g. `1152x2048` for a tall 9:16). Explicit values must total 262,144..4,194,304 pixels with an aspect ratio (W/H) in 1/8..8; anything outside is rejected with `400 validation_error` before any debit. A preset is always resolved to explicit pixels before generation — see `aspectRatio` for which shape you get. Billing is size-based, and an explicit `WxH` bills at the tier its pixel area falls into.

Example: "2K"

Shape of a preset `size`: `square` (1:1), `landscape` (16:9), `portrait` (3:4). **Specific to this model:** `auto` does not hand the choice to the model — it resolves to the square shape of the chosen preset, because this model is always sent explicit pixels. The exact dimensions behind a preset are not a fixed contract; read the delivered size back from `images[].size`, or pass an explicit `WxH` to pin it (an explicit size wins and `aspectRatio` is then ignored). Billing follows the size tier, so the shape never changes the price.

Example: "landscape"

How many images to generate in this single request. 1–6. They are produced together in one pass rather than one after another, so several images take about as long as one. Each image is billed at the size-based rate. Independent of how many input images you pass — the two are separate budgets.

Example: 4

What should NOT appear in the image, as plain comma-separated text — no weights and no special syntax. Effective against the usual artefacts of this model class: `text, watermark, logo, extra fingers`.

Example: "text, watermark, logo, extra fingers"

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. One exception, and it is this model's own: with `promptExtend: true` the prompt is rewritten before generation and the rewrite differs between runs, so the same seed no longer guarantees the same image. Leave `promptExtend` off when you need reproducibility.

Example: 42

Whether to add a small platform watermark in the corner.

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

Not supported by this model — it returns independent images only. Passing `"auto"` is rejected with `400 validation_error` before any debit. Use `n` for several images in one request, or xSD 4.5 for a connected series.

Let the model rewrite your prompt into a longer, more detailed one before generating. Off by default. It usually helps short or sketchy prompts and gets in the way of carefully written ones — the prompt that runs is not the prompt you sent. Note the consequence for `seed`: the rewrite differs between runs, so with this on the same seed no longer guarantees the same image.

Example: true

How the prompt is rewritten when `promptExtend` is on. `"direct"` expands it in one pass. `"agent"` is a slower, more elaborate rewrite and is **text-to-image only** — combined with `references` it is rejected with `400 validation_error` before any debit. Has no effect when `promptExtend` is off.

Example: "direct"

Let the model reason about the rewritten prompt before generating: better prompt adherence and composition, at a real cost in time — a request goes from a few seconds to well over a minute (measured 66-85 s), and that overhead is per request, not per image. Requires `promptExtend: true`; sent on its own it is rejected with `400 validation_error` before any debit.

Example: true

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, PNG) 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.

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).