xSD 5.5
Precise step-by-step editing and native transparent PNGs.
xSD 5.5 is the newest model of the xSD 5 line, tuned for editing: it keeps a subject's features, composition and style steady across successive edits of the same image. It renders native transparent PNGs straight from a prompt or from reference images, for stickers, icons and product cut-outs. It takes no seed — it refines every prompt before generating, so two runs of the same request differ.
- Successive edits stay consistent: feed each result back as the next reference
- Transparent background on request — from a prompt alone or from ordinary reference images
- JPEG or PNG output, and one per-image rate at every size, references included
- 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.
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.
Quick example
Send a generation in 5 lines. Pick your language below.
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": "xSD5.5",
"prompt": "A ceramic coffee mug on a wooden table by a window, morning light, steam rising, shallow depth of field"
}'Request parameters
The fields you can include in the request body. Anything not listed is ignored.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
endUserEmail | string (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: |
prompt | string | yes | — | Text prompt describing the image. Best results follow the structure: subject + action + environment, then style + lighting + composition. For an edit, say what to change AND what to keep ("add sunglasses; keep the face, hair, clothing and background"). For a transparent result, describe the isolated subject. 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: |
model | string | yes | — | Public model alias. Required — pass `xSD5.5` to use this model. See the list of currently available aliases in the docs. Example: |
references | string | string[] | no | — | The image to edit, or images to take a face, character or style from. Single HTTPS URL or an array of them — up to `maxReferences` from `GET /v1/models`. For step-by-step editing, pass the previous result as the reference and describe only the next change. When using several, name them in the prompt (e.g. "use image_1 for the face, image_2 for the outfit"). References need no transparency of their own, even for a transparent result. Example: |
size | string | no | "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). Explicit-pixel values must have total pixels in 0.92M – 4.62M 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. Combine with `aspectRatio` to pick a specific aspect under a preset. When `size` is explicit `WxH`, any `aspectRatio` is ignored (explicit `size` wins). Example: |
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`). The exact pixels are not a fixed contract — read the delivered size back from `images[].size`, or pass an explicit `WxH` size to pin it. `auto` (default) lets the model pick the shape from the prompt and the references. Example: |
n | integer | no | 1 | 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: |
outputFormat | "jpeg" | "png" | no | "jpeg" ("png" when background is "transparent") | File format of the result. `jpeg` (default) gives smaller files; `png` is lossless and is the only format that carries transparency, so it becomes the default when `background` is `transparent`. Asking for `jpeg` together with a transparent background is rejected with `400 validation_error` before any debit. The file name in the delivered URL's path ends in `.jpg` or `.png` accordingly (the URL itself carries a signature query string after it). Example: |
background | "opaque" | "transparent" | "auto" | no | "opaque" | `opaque` (default) — a normal image with no alpha channel. `transparent` — a native transparent background, for stickers, icons and product cut-outs; works from a prompt alone and with references, which need no transparency themselves. Requires `png`. `auto` — the model decides from the prompt (on `jpeg` the result is always opaque). For step-by-step edits keep it `opaque` — a non-transparent result keeps successive edits most consistent. Example: |
watermark | boolean | no | false | Whether to add a small platform watermark in the corner. |
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. |
webhookUrl | string (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: |
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.
{
"requestId": "req_3kT9wQ2mZpL7vXnB",
"model": "xSD5.5",
"status": "queued",
"prompt": "A cute cartoon fox sticker with a thick white outline, flat colours",
"referencesCount": 0,
"endUserEmail": "alice@your-product.com",
"createdAt": "2026-11-16T15:02:11.481Z",
"pollUrl": "https://api.xmode.ai/v1/generations/req_3kT9wQ2mZpL7vXnB"
}| Name | Type | Required | Default | Description |
|---|---|---|---|---|
requestId | string | yes | — | Unique id of the generation. Use it with GET /v1/generations/:requestId to poll. |
model | string | yes | — | 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. |
pollUrl | string | no | — | Present on `queued` responses only. Absolute URL to GET for status. Recommended polling cadence: every 5 seconds until terminal. |
images | array | no | — | 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. |
error | object | no | — | 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). |
cost | object | no | — | Present only when status=`succeeded`. `{ xTokens: number }`. Debited at request time; refunded automatically on `failed`. |
finishedAt | string (ISO 8601) | no | — | Present on terminal statuses (`succeeded`, `failed`, `expired`). When the generation reached its final state. |
endUserEmail | string | yes | — | Echoed back so you can confirm the grouping. Always lowercase. |
createdAt | string (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 JPEG at the default size (2K).
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": "xSD5.5",
"prompt": "A ceramic coffee mug on a wooden table by a window, morning light, steam rising, shallow depth of field"
}'Transparent sticker from a prompt
Ask for `background: "transparent"` and the result is a PNG with an alpha channel — `outputFormat` defaults to `png` here, so it can be left out. Describe the isolated subject; there is nothing behind it to describe.
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": "xSD5.5",
"prompt": "A cute cartoon fox sticker with a thick white outline, flat colours",
"background": "transparent",
"size": "2K",
"aspectRatio": "square"
}'Cut-out from ordinary photos
References need no transparency of their own: the model extracts the subjects and returns them on a transparent background.
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": "xSD5.5",
"prompt": "Extract the sneaker from image_1 and the backpack from image_2 and place both on a transparent background, side by side, without overlap, edges sharp and intact",
"references": [
"https://example.com/sneaker.jpg",
"https://example.com/backpack.jpg"
],
"background": "transparent"
}'Step-by-step editing
Edit the same image over several requests: pass the previous result as the only reference, describe the next change, and say what must stay. Keep the background opaque for the most consistent chain.
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": "xSD5.5",
"prompt": "Add round sunglasses. Keep the face, hairstyle, earrings, clothing, pose, background and composition unchanged.",
"references": "https://example.com/previous-result.jpg",
"size": "2K"
}'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 -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": "xSD5.5",
"prompt": "Product packshot of a glass perfume bottle on a pale stone plinth, soft studio light",
"outputFormat": "png",
"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