Sign in
ActivePOST /v1/generations

xSD 5 Flash

Fast image model: strong layouts, clean in-image text, one rate at every size.

xSD 5 Flash is the quick tier of the xSD 5 line, built for work you produce in volume and iterate on. It is at its best on layout — font variety, composition and bright, faithful colour — which suits covers, ads and anything with type in it. It generates one or more images from a prompt, and can anchor a face, transfer a style or compose several subjects from reference images. Prompts may be written in a wide range of languages, not only English.

  • Built for volume: ad creative, editorial visuals, UGC and anything you iterate on
  • Every preset bills at the same per-image rate, so 2K is the default rather than an upgrade
  • Reference images for face anchoring, style transfer and multi-subject composition
  • Independent images only — for a connected series use xSD 4.5

Generation is asynchronous. POST answers `202` with a `requestId` and a `pollUrl`; the result arrives by polling that URL or through an HMAC-signed webhook when you pass `webhookUrl`. Signed output URLs stay valid for 23 hours.

Authentication. Add Authorization: Bearer xm_live_… to every request.

How to get an API key

Account responsibility. Every request must include the real email of YOUR end-user via endUserEmail. You are accountable for what they generate — monitor activity and act on abuse, or your account may be suspended.

Read acceptable use

Quick example

Send a generation in 5 lines. Pick your language below.

curl
curl -X POST https://api.xmode.ai/v1/generations \
  -H "Authorization: Bearer xm_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "endUserEmail": "alice@your-product.com",
  "model": "xSD5Flash",
  "prompt": "Product packshot of a matte black espresso machine on a raw concrete surface, hard side light, deep shadow, minimal studio set"
}'

Request parameters

The fields you can include in the request body. Anything not listed is ignored.

NameTypeRequiredDefaultDescription
endUserEmailstring (email)yes—

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"

promptstringyes—

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"). This model reads prompts in a wide range of languages, not only English.

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

modelstringyes—

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

Example: "xSD5Flash"

referencesstring | string[]no—

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"]

sizestringno"2K"

Output dimensions. Preset `1K`, `1.5K` or `2K` (this model does not support `4K`), or explicit pixels (e.g. `1440x2560` for a tall 9:16). Defaults to `2K`. 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. Every size on this model bills at the same per-image rate — there is no cheaper tier to drop to, so pick the size you actually want. 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"

aspectRatio"auto" | "square" | "landscape" | "portrait"no"auto"

Convenience selector for aspect ratio: `square` (1:1), `landscape` (16:9), `portrait` (3:4). Combine with a preset `size` and the server resolves to the dimensions this model is tuned for (e.g. `size: "2K"` + `aspectRatio: "landscape"` → `2816x1584`, `+ "portrait"` → `1776x2368`). 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. `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"

nintegerno1

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. Each image is billed separately.

Example: 4

seedintegernorandom (server-generated)

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

watermarkbooleannofalse

Whether to add a small platform watermark in the corner.

guidanceScalenumberno~7.5

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

Example: 7.5

responseFormat"url" | "b64_json"no"url"

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.

sequential"auto" | "disabled"no"disabled"

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.

webhookUrlstring (https URL)no—

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"

Response

The POST answers 202 Accepted with this shape — the job is queued, not finished. Read the result from pollUrl, which returns the same record with the fields below filled in. Output URLs are signed and valid for 23 hours.

JSON
{
  "requestId": "req_8pR2mV6cHtY4nQwK",
  "model": "xSD5Flash",
  "status": "queued",
  "prompt": "Product packshot of a matte black espresso machine on a concrete surface",
  "referencesCount": 0,
  "endUserEmail": "alice@your-product.com",
  "createdAt": "2026-10-13T18:45:15.204Z",
  "pollUrl": "https://api.xmode.ai/v1/generations/req_8pR2mV6cHtY4nQwK"
}
NameTypeRequiredDefaultDescription
requestIdstringyes—

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

modelstringyes—

Public alias of the model that will produce the images.

status"queued" | "processing" | "succeeded" | "failed" | "expired"yes—

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.

pollUrlstringno—

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

imagesarrayno—

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.

errorobjectno—

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

costobjectno—

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

finishedAtstring (ISO 8601)no—

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

endUserEmailstringyes—

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

createdAtstring (ISO 8601)yes—

When the request was accepted (POST time).

Use cases

Common patterns. Copy any block, replace the API key, and you have a runnable request.

Text to image

Simplest case. Just a prompt, the model alias, and the end-user email. Returns 1 image at default size (2K).

curl
curl -X POST https://api.xmode.ai/v1/generations \
  -H "Authorization: Bearer xm_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "endUserEmail": "alice@your-product.com",
  "model": "xSD5Flash",
  "prompt": "Product packshot of a matte black espresso machine on a raw concrete surface, hard side light, deep shadow, minimal studio set"
}'

Poster with text in it

Put the words that must appear in the image in double quotes. Type and layout are what this model is tuned for.

curl
curl -X POST https://api.xmode.ai/v1/generations \
  -H "Authorization: Bearer xm_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "endUserEmail": "alice@your-product.com",
  "model": "xSD5Flash",
  "prompt": "Event poster, large headline \"NIGHT MARKET\" in a condensed sans serif, smaller line \"Fridays from 6pm\", street food stalls under string lights, warm amber and deep teal",
  "size": "2K",
  "aspectRatio": "portrait"
}'

Single reference (face anchor)

Pass one HTTPS URL as `references`. The model preserves face/style/lighting from the reference unless overridden by the prompt.

curl
curl -X POST https://api.xmode.ai/v1/generations \
  -H "Authorization: Bearer xm_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "endUserEmail": "alice@your-product.com",
  "model": "xSD5Flash",
  "prompt": "Make her wear a leather jacket on a snowy New York street at dusk. Cinematic still.",
  "references": "https://images.pexels.com/photos/1239291/pexels-photo-1239291.jpeg",
  "size": "2K"
}'

A batch of variations

Set `n` to generate variations in a single call — the usual way to work with this model. Each image is billed separately at the same per-image rate.

curl
curl -X POST https://api.xmode.ai/v1/generations \
  -H "Authorization: Bearer xm_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "endUserEmail": "alice@your-product.com",
  "model": "xSD5Flash",
  "prompt": "Flat-illustration app onboarding scene, soft gradient background, friendly geometric characters",
  "size": "2K",
  "n": 6
}'

Skip polling — receive a webhook

Pass `webhookUrl` and we POST the final record there once the generation is done. No need to poll. The body is the same shape as GET /v1/generations/:requestId. Verify `X-XMode-Signature: v1=<hex>` against your account webhook secret (HMAC-SHA256 of `"<timestamp>.<rawBody>"`).

curl
curl -X POST https://api.xmode.ai/v1/generations \
  -H "Authorization: Bearer xm_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "endUserEmail": "alice@your-product.com",
  "model": "xSD5Flash",
  "prompt": "Polaroid-style portrait of a woman with freckles, soft daylight",
  "size": "2K",
  "webhookUrl": "https://your-app.example.com/hooks/xmode"
}'

Limits

  • Max images per request (`n`): 15
  • Max references: 10
  • Max reference size: 10 MB per reference
  • Total pixels range: 0.92M – 4.62M (presets 1K ≈1 MP, 1.5K ≈2.4 MP, 2K ≈4 MP)
  • Aspect ratio range: 1/16 – 16
  • Prompt max length: 8000 characters
Errors follow our standard format — see all error codes →