Overview

How a generation request works: capabilities, the request body, the async job lifecycle, polling, cancellation and the errors you'll see at submit.

Every generation in Windpaint is an asynchronous job. You ask for a capability, such as image.generate or video.generate, optionally name the model that should run it, and get back a request_id straight away. The job runs in the background; when it finishes, its outputs are stored as assets in your project and listed on the request’s status.

curl -X POST https://api.windpaint.ai/v1/generation/capabilities/image.generate \
  -H "Authorization: Bearer $WINDPAINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a lighthouse at dusk, film grain"}'

{
  "status": "queued",
  "request_id": "0f6c1d2e-8a3b-4c5d-9e7f-1a2b3c4d5e6f",
  "status_url": "https://api.windpaint.ai/v1/generation/requests/0f6c1d2e-8a3b-4c5d-9e7f-1a2b3c4d5e6f/status",
  "cancel_url": "https://api.windpaint.ai/v1/generation/requests/0f6c1d2e-8a3b-4c5d-9e7f-1a2b3c4d5e6f/cancel",
  "credits_estimate": "0.08"
}

There is no synchronous mode. You either poll status_url until the job reaches a terminal status, or pass a webhook_url and wait for a POST.

Capabilities and models

A capability is a typed operation: what it takes (a prompt, and zero or more input assets in named slots) and what it produces (an image, a video, and so on). A model is one implementation of a capability, with its own resolutions, durations and prices.

You address the capability in the URL and may name a model in the body. Leave model out and Windpaint uses the capability’s first available model. Two capabilities have a live model today: image.generate (z-image-turbo) and video.generate (wan-2.2-i2v). The rest are defined and listed by the API but can’t be submitted yet. See Models for the full table and current prices.

Submit a request

curl -X POST https://api.windpaint.ai/v1/generation/capabilities/image.generate \
  -H "Authorization: Bearer $WINDPAINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-turbo",
    "prompt": "a lighthouse at dusk, film grain",
    "resolution": "1k",
    "aspect_ratio": "16:9",
    "seed": 42
  }'

A successful submit returns 202 Accepted with the body shown above. The body is not wrapped in data; submit, status and cancel all return bare objects.

Request body

Every field is optional except where a capability requires it. Fields the chosen model doesn’t support are rejected with 422, not ignored.

Each request produces one output: one image for image.generate, one clip for video.generate. To get several variations, submit several requests with different seeds.

Job lifecycle

Failure messages

A failed job’s error is one of these fixed messages. The same text appears in job webhooks and, prefixed with the step key, on a failed product run.

All of them are safe to resubmit once; nothing was charged. If the same request keeps failing, try another model or contact support with the request_id.

Read the status

GET /v1/generation/requests/{request_id}/status returns the job. It finds the job anywhere in your organization, so it works without a project header.

{
  "status": "completed",
  "request_id": "0f6c1d2e-8a3b-4c5d-9e7f-1a2b3c4d5e6f",
  "capability": "image.generate",
  "model": "z-image-turbo",
  "project_id": "5b0c7e1a-2f3d-4e5f-8a9b-0c1d2e3f4a5b",
  "source": "api",
  "outputs": [
    {
      "id": "d77a4c1e-9b2f-4a3d-8e6f-7a8b9c0d1e2f",
      "url": "https://api.windpaint.ai/v1/generation/assets/d77a4c1e-9b2f-4a3d-8e6f-7a8b9c0d1e2f/content",
      "content_type": "image/png",
      "width": 1024,
      "height": 576,
      "duration_s": null
    }
  ],
  "images": [
    {
      "id": "d77a4c1e-9b2f-4a3d-8e6f-7a8b9c0d1e2f",
      "url": "https://api.windpaint.ai/v1/generation/assets/d77a4c1e-9b2f-4a3d-8e6f-7a8b9c0d1e2f/content",
      "content_type": "image/png",
      "width": 1024,
      "height": 576,
      "duration_s": null
    }
  ],
  "video": null,
  "credits": { "estimate": "0.08", "actual": "0.08" },
  "error": null,
  "created_at": "2026-10-04T14:02:11.418Z",
  "finished_at": "2026-10-04T14:02:15.902Z"
}

GET /v1/generation/requests?limit=50 lists the jobs in the current project, newest first, as {"data": [ ... ]} with the same object per job. limit takes 1 to 200.

Poll until done

Start polling a second or two after submit and back off, capping the interval around 15 seconds. An image is usually done within the first few polls; a video can take several minutes, so give video loops a generous overall timeout. There are no rate-limit headers to read today, but polling faster than this doesn’t make the job finish sooner.

import os
import time
import requests

API = "https://api.windpaint.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['WINDPAINT_API_KEY']}"}
TERMINAL = {"completed", "failed", "nsfw", "canceled"}


def wait(request_id: str, timeout_s: float = 1200) -> dict:
    delay, deadline = 1.5, time.monotonic() + timeout_s
    while True:
        resp = requests.get(f"{API}/generation/requests/{request_id}/status", headers=HEADERS)
        resp.raise_for_status()
        job = resp.json()
        if job["status"] in TERMINAL:
            return job
        if time.monotonic() > deadline:
            raise TimeoutError(f"{request_id} still {job['status']}")
        time.sleep(delay)
        delay = min(delay * 1.5, 15)


job = wait("0f6c1d2e-8a3b-4c5d-9e7f-1a2b3c4d5e6f")
if job["status"] != "completed":
    raise RuntimeError(f"{job['status']}: {job['error']}")
print(job["outputs"][0]["url"])

The CLI’s run and status --wait exit with code 9 when the job ends failed, nsfw or canceled, and 10 when --timeout (15 minutes by default) passes first.

Cancel a job

curl -X POST https://api.windpaint.ai/v1/generation/requests/$REQUEST_ID/cancel \
  -H "Authorization: Bearer $WINDPAINT_API_KEY"

Cancel returns the job’s status object. What it does depends on where the job is:

• queued: the job is marked canceled and never runs.
• in_progress: the job is marked canceled right away. A render that’s already running isn’t interrupted, but its output is discarded and never appears in your project.
• Terminal: nothing changes; you get the job back as it was.

In every case where the job ends canceled, the held credits are released in full. The CLI equivalent is windpaint cancel <request-id>.

Projects

Every job runs inside one project, and its outputs are stored there. The project is picked in this order:

1. project_id in the request body.
2. The X-Windpaint-Project header, by id or slug.
3. Your organization’s default project.

curl -X POST https://api.windpaint.ai/v1/generation/capabilities/image.generate \
  -H "Authorization: Bearer $WINDPAINT_API_KEY" \
  -H "X-Windpaint-Project: launch-video" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a paper boat in the rain"}'

The CLI sends --project, WINDPAINT_PROJECT or the project saved with windpaint projects select as that header. Listing requests and assets is scoped to the project the same way. Submitting into an archived project returns 409, and naming a project outside your organization returns 404. Credits come from the organization’s balance whichever project you use. See Organizations and projects.

Retries and double billing

The API has no idempotency keys. If you retry a submit after a timeout or a dropped connection, and the first request actually reached the server, you get two jobs and pay for both.

To retry safely, check before you resubmit. GET /v1/generation/requests lists the project’s recent jobs newest first; if a job with your capability, model and created_at around the time of your first attempt is already there, poll that one instead.

from datetime import datetime, timedelta, timezone

sent_at = datetime.now(timezone.utc) - timedelta(seconds=5)  # recorded just before the first attempt

# ... first attempt timed out ...

recent = requests.get(f"{API}/generation/requests?limit=20", headers=HEADERS).json()["data"]
already = [
    r for r in recent
    if r["capability"] == "image.generate"
    and datetime.fromisoformat(r["created_at"].replace("Z", "+00:00")) >= sent_at
]
if already:
    job = wait(already[0]["request_id"])

Jobs don’t echo the prompt back, so if you submit many similar jobs at once, record each request_id as soon as you get it and match on time rather than retrying blindly.

Errors at submit

Submit validates everything before it creates a job, so a request that’s rejected costs nothing. Errors use the standard envelope:

{
  "error": {
    "code": "billing.insufficient_credits",
    "message": "Not enough credits: this needs 4.00 and 1.20 are available.",
    "details": { "required": "4.00", "available": "1.20" },
    "request_id": "86926749.37e5a9"
  }
}

A body that isn’t valid JSON or has a field of the wrong type returns 400 with request.validation_failed. Authentication errors (401, 403) use a different body; see Errors for the full list.