Get a generation

Read one image generation by id. This is how you collect the result of `POST /v1/generations`: the POST returns `202` and nothing else, so either you poll this endpoint or you supply `webhookUrl` and we call you.

`GET /v1/generations/{requestId}`

Current state of one image generation.

The response is a `GenerationRecord` — a discriminated union on `status`, so which fields exist depends on where the generation is:

- `queued` — the base record plus `pollUrl`. No `images`, no `cost`, no `finishedAt`. - `processing` — the base record only. `pollUrl` is present on `queued` alone; keep the URL you were given. - `succeeded` — adds `images[]`, `cost` and `finishedAt`. Each image carries `id`, `size` and `expiresAt`, plus EITHER `url` or `error: { code: "storage_failed" }`. - `failed` — adds `error: { code, message }` and `finishedAt`. xTokens are refunded automatically; the refund is applied just after the status flips, so a poll that catches the transition can briefly show `failed` before the credit lands. - `expired` — adds `finishedAt`. The signed URLs are gone; the record itself is kept for 90 days.

**Poll every 5 seconds** until `status` is terminal (`succeeded`, `failed`, `expired`). An image takes from a few seconds to a couple of minutes, depending on the model and its options. There is no long-poll and no cost to reading — this endpoint never debits.

**URLs are re-signed on every read.** A link that went stale on your side is replaced simply by reading the record again. That does NOT move `expiresAt`, which is fixed when the generation completed — once it passes, the record comes back `expired` and the bytes are gone.

Reading a video id here returns `404`: images and video are separate surfaces, and `GET /v1/videos/{requestId}` is the video one. (Deletion is the exception — `DELETE /v1/generations/{requestId}` removes either kind.)

bash

# Request
curl 'https://api.xmode.ai/v1/generations/req_3xN7kQ1aJpL9wDvE' \
  -H "Authorization: Bearer xm_live_<your-key>"

# 200 OK — still running
{
  "requestId": "req_3xN7kQ1aJpL9wDvE",
  "model": "xSD4.5",
  "status": "processing",
  "prompt": "Editorial photo of a cat in space, cinematic, 85mm portrait lens",
  "referencesCount": 0,
  "endUserEmail": "alice@your-product.com",
  "createdAt": "2026-05-02T19:45:15.204Z"
}

# 200 OK — done
{
  "requestId": "req_3xN7kQ1aJpL9wDvE",
  "model": "xSD4.5",
  "status": "succeeded",
  "prompt": "Editorial photo of a cat in space, cinematic, 85mm portrait lens",
  "referencesCount": 0,
  "endUserEmail": "alice@your-product.com",
  "createdAt": "2026-05-02T19:45:15.204Z",
  "finishedAt": "2026-05-02T19:45:41.882Z",
  "images": [
    {
      "id": "img_7bQ2xL",
      "url": "https://cdn.xmode.ai/...",
      "size": "2048x2048",
      "expiresAt": "2026-05-03T18:45:41.882Z"
    }
  ]
}

# 404 Not Found — unknown id, not yours, or a video id
{
  "error": { "code": "not_found", "message": "Generation not found" }
}