Get Generation Status API

Poll a thumbnail generation job for status and output URLs.

Poll a thumbnail generation job for its current status and output URLs. Call this endpoint after POST /api/v1/generate returns a generationId and repeat every few seconds until status is succeeded, failed, or partial.

Endpoint

GET /api/v1/generations/:id

Authentication

Same API key as POST /api/v1/generate. Pass it as a Bearer token or x-api-key header:

Authorization: Bearer nsk_YOUR_KEY

Path parameter

Parameter	Type	Description
`:id`	string	The `generationId` returned by `POST /api/v1/generate`.

Response

Field	Type	Description
`id`	string	Generation ID.
`status`	string	`"processing"` \| `"succeeded"` \| `"failed"` \| `"partial"`
`model`	string	Model used: `"gemini-3-pro"` or `"gpt-image-2"`.
`count`	number	Number of variations requested.
`createdAt`	number	Unix ms timestamp.
`thumbnails`	array	One entry per variation (see below).

Thumbnail object

Field	Type	Description
`id`	string	Thumbnail ID.
`status`	string	`"processing"` \| `"succeeded"` \| `"failed"`
`url`	string \| null	Download URL for the 1280 × 720 PNG. `null` while processing or if `isHidden`.
`isWatermarked`	boolean	`true` on the free tier (clean URL is never exposed).
`isHidden`	boolean	`true` if the thumbnail was taken down by a safety review.
`error`	string \| null	Human-readable error summary if `status` is `"failed"`. Safety errors are genericised — no provider detail is exposed.

Watermark policy

Free-tier organisations always receive the watermarked URL in url. The clean imageUrl is never serialised in the API response. Upgrade to a paid plan to get clean, unwatermarked downloads.

Cross-org isolation

A generation ID from org A always returns 404 when queried with a key from org B — even if the ID is guessed correctly. Generation rows are strictly org-scoped.

Polling guidance

POST /api/v1/generate → generationId
  ↓
loop:
  GET /api/v1/generations/:id → status
  if status in (succeeded, failed, partial) → done
  else wait 3–5 s → repeat

Typical generation time is 20–60 s depending on model and count. A practical poll interval is 3–5 s. Do not poll faster than once per second.

Examples

cURL

curl -H "Authorization: Bearer nsk_YOUR_KEY" \
  https://fatthumb.klaas.pro/api/v1/generations/jd7abc1234

JavaScript (with polling loop)

async function waitForGeneration(
  generationId: string,
  apiKey: string,
  intervalMs = 3000,
): Promise<{ thumbnails: { url: string | null }[] }> {
  while (true) {
    const response = await fetch(
      `https://fatthumb.klaas.pro/api/v1/generations/${generationId}`,
      { headers: { Authorization: `Bearer ${apiKey}` } },
    );

    if (!response.ok) {
      throw new Error(`Poll failed: ${response.status}`);
    }

    const data = await response.json();
    if (["succeeded", "failed", "partial"].includes(data.status)) {
      return data;
    }

    await new Promise((r) => setTimeout(r, intervalMs));
  }
}

Python

import os, requests, time

def wait_for_generation(generation_id: str, interval_s: int = 3):
    api_key = os.environ["FATTHUMB_API_KEY"]
    while True:
        resp = requests.get(
            f"https://fatthumb.klaas.pro/api/v1/generations/{generation_id}",
            headers={"Authorization": f"Bearer {api_key}"},
        )
        resp.raise_for_status()
        data = resp.json()
        if data["status"] in ("succeeded", "failed", "partial"):
            return data
        time.sleep(interval_s)

Errors

Status	Description
`401`	Missing or invalid API key.
`404`	Generation not found, or belongs to a different organisation.
`429`	Rate limit exceeded — retry after a moment.
`500`	Internal server error.