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"
}
To get the result you can poll status_url until the job reaches a terminal status, stream its progress, pass a webhook_url and wait for a POST, or send Prefer: wait and let the API hold the response until the job finishes (see synchronous mode).
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. One capability has live models today: image.generate, with z-image-turbo (the default) and flux-2-klein-4b. video.generate is coming soon with 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.
There is also a model-addressed form, POST /v1/generation/models/{model}, which takes image_urls (a list of input references that fill the model’s main input slot) instead of inputs. It runs the same job. The capability form is the one these docs use.
Submit a request
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.
Always queued on submit.
The job’s id. Use it with the status and cancel endpoints.
GET this to read the job’s status.
POST to this to cancel the job.
The price of this job in credits, as a decimal string. It’s fixed at submit and held against your balance until the job finishes.
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.
The model to run, e.g. z-image-turbo. Defaults to the capability’s first available model. See default model selection.
What to generate. Required for every capability except media.upscale and video.lipsync. An empty or whitespace-only prompt on a capability that needs one returns 422.
Input assets by slot name, each a list: {"start_frame": ["<asset id>"]}. Each value is an asset id, an asset URL this API returned, a public https:// URL, or a data: URI. URLs and data URIs are fetched at submit and stored as new assets in the job’s project; see Inputs for formats and limits. Each asset must be in the same project as the job and of a kind the slot accepts. The slots a capability has, and how many assets each takes, are listed by GET /v1/generation/capabilities.
The resolution tier: 1k for images, 480p for video (coming soon). Defaults to the model’s default tier. See resolution tiers.
One of 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 21:9, 4:5, 5:4. Defaults to 16:9 for video and 1:1 for everything else.
Reserved for models with quality tiers. No current model has any, so sending a value returns 422.
Clip length in seconds, for models that take one. wan-2.2-i2v (coming soon) will take 5 only, which is also the default. Sending a duration to an image model returns 422.
Random seed. The same seed, prompt and settings on the same model give you the same output, which is how you reproduce a result. Omit it for a random seed; the API doesn’t report which seed it used, so pass one whenever you might want to reproduce the output.
How many images to make in this job, from 1 to the model’s max_outputs (4 for z-image-turbo). Video models take 1 only. See multiple outputs.
png, jpeg (or jpg) or webp, for models that list output_formats. Video models reject it.
Encoding quality from 1 to 100, for jpeg and webp only.
A Windpaint preset, as <slug> or <slug>@<version>. It wraps your prompt in a template and fills settings you leave unset.
auto or low. low relaxes the content filter for every category except the hard ones. See Moderation.
Keep this job’s outputs for fewer days than your organization’s setting, from 1 to 365. A larger value is clamped to the organization’s setting. See Retention.
An https URL that receives a signed POST with the job’s status when it finishes. Failed deliveries are retried. See Webhooks.
Which events to send to webhook_url: started, completed, or both. Requires webhook_url.
The project to run in, by id. Takes precedence over the X-Windpaint-Project header. See projects.
Two headers change how a submit behaves:
Idempotency-Key: <string>makes a retried submit return the original job instead of creating a second one. See Retries and double billing.Prefer: waitholds the response until the job finishes, up to 60 seconds. See synchronous mode.
Multiple outputs
An image job makes one image by default. Set num_outputs to get up to the model’s max_outputs images from one job; z-image-turbo makes up to 4. Video models make one clip per request and return 422 for any other value.
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", "num_outputs": 4, "output_format": "webp", "output_quality": 85}'
- Price. One request is one job. The hold and
credits_estimateare the unit price timesnum_outputs: four1kimages onz-image-turbohold0.32credits. - Outputs.
outputsandimageslist the delivered images in order. The status also reports the requestednum_outputs. - Partial results. If the model returns fewer usable images than you asked for, the job still ends
completedwith what was delivered. You’re charged the unit price times the number delivered, and the rest of the hold is released. If nothing is delivered, the job isfailedand nothing is charged. - Format. Models produce PNG, and Windpaint re-encodes each output to
output_formatbefore storing it. JPEG has no transparency, so transparent areas become white.content_typeon each output matches the format.
GET /v1/generation/capabilities lists max_outputs and output_formats for every model. Steps of a workflow run always make one output in the default format.
Job lifecycle
Submit
POST /v1/generation/capabilities/{capability} validates the request, prices it, holds the credits and returns 202 with status: "queued".
Run
A worker picks up the job and moves it to in_progress. Images usually take seconds. Video takes several minutes.
Finish
The job lands in one terminal status. On completed, the held credits are charged and the outputs are stored in your project. Every other terminal status releases the hold in full, so failed jobs cost nothing.
| Status | Meaning | Terminal | Credits |
|---|---|---|---|
queued | Accepted, waiting for a worker | No | Held |
in_progress | Rendering | No | Held |
completed | At least one output was stored | Yes | Charged (per delivered output) |
failed | The render failed or produced no output; see error_code | Yes | Released |
nsfw | The output was blocked by content moderation, or the model refused the request | Yes | Released |
canceled | Canceled before it finished | Yes | Released |
Failure messages
A job that ends failed, nsfw or canceled has an error_code and an error. Branch on error_code, a stable code such as job.timeout or job.input_invalid; the full list, with which codes are worth retrying, is in job error codes and at GET /v1/errors. error is a human-readable message. The same fields appear in job webhooks and on a failed workflow run.
A failed job’s error is one of these fixed messages:
error | Meaning |
|---|---|
Generation failed upstream (HTTP <status>). Credits were released. | The model backend answered with an HTTP error, for example HTTP 500. |
Generation failed: the model backend is unavailable. Credits were released. | The model backend couldn’t be reached or kept timing out after retries. |
Generation failed: the model backend could not complete the request. Credits were released. | The model backend rejected or couldn’t finish the request. |
Generation failed: the model returned no output. Credits were released. | The render finished without producing a file. |
Generation failed due to an internal error. Credits were released. | Something failed on Windpaint’s side. |
A job blocked by moderation has error The output was blocked by content moderation. Credits were released. (or Generation blocked: the provider refused the content. Credits were released. when the model refused it), and a canceled job has Canceled before it finished. Credits were released.
Nothing was charged for any of these. Codes marked retryable in the catalog are worth one more try; for the others, change the request first. 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,
"num_outputs": 1,
"preset": null,
"credits": { "estimate": "0.08", "actual": "0.08" },
"error": null,
"error_code": null,
"moderation": null,
"queue_position": null,
"progress": 1,
"logs": [
{ "at": "2026-10-04T14:02:12.001Z", "message": "Started" },
{ "at": "2026-10-04T14:02:15.640Z", "message": "Saving outputs" },
{ "at": "2026-10-04T14:02:15.902Z", "message": "Completed" }
],
"timings": { "queue_s": 0.583, "run_s": 3.901 },
"created_at": "2026-10-04T14:02:11.418Z",
"started_at": "2026-10-04T14:02:12.001Z",
"completed_at": "2026-10-04T14:02:15.902Z",
"finished_at": "2026-10-04T14:02:15.902Z"
}
One of the statuses above.
The capability that ran.
The model that ran, including when you left model out.
The project the job and its outputs belong to.
Where the job came from: api (an API key), studio (the dashboard) or workflow (a step of a workflow run).
Every asset the job produced, of any kind. Empty until the job completes.
The image entries of outputs, as a shortcut.
The first video entry of outputs, as a shortcut.
How many outputs were requested. outputs can hold fewer after a partial result.
{"slug", "version"} of the preset the job used, or null.
estimate is the price fixed at submit. actual is what was charged once the job completes: the unit price times the outputs delivered. null otherwise.
A human-readable message when the job ended failed, nsfw or canceled. See failure messages. null otherwise.
A stable code when the job ended failed, nsfw or canceled, such as job.timeout. null otherwise. See job error codes.
Set when output moderation blocked the job: {"code": "moderation.output_blocked", "stage": "output", "categories": [...]}. null otherwise.
While queued, how many jobs are ahead of this one (0 means next). null once it starts.
Fraction from 0 to 1 while running, when the model backend reports it. 1 once completed. See progress and logs.
Short status lines, oldest first, each {"at", "message"}. Empty while queued.
queue_s (submit to start) and run_s (start to finish, null until started), in seconds. Both count up while that phase is ongoing.
When the job was submitted (ISO 8601).
When a worker picked the job up.
When the job reached a terminal status. Same value as finished_at, which is kept.
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.
Progress and logs
While a job runs, its status shows where it is:
queue_positioncounts the jobs ahead of it while it’squeued, across all customers.0means it’s next.progressis a fraction from 0 to 1 when the model backend reports one. Some backends report nothing until the job finishes, so it can staynullwhile running. It resets tonullif the job is retried on another backend.logsholds short lines with fixed wording:Started,The model backend is busy; retrying (attempt 2 of 3),Switching to another backend for this model,Saving outputs, then one ofCompleted,Failed,Blocked by the content filterorCanceled. Failure details stay inerror.timingsgives the time spent queued and running, in seconds.
To get these as they change instead of polling, open the job’s event stream at GET /v1/generation/requests/{request_id}/stream (Server-Sent Events). It sends status, progress, log and a final done event, then closes. See Stream a job.
curl -N https://api.windpaint.ai/v1/generation/requests/$REQUEST_ID/stream \
-H "Authorization: Bearer $WINDPAINT_API_KEY"
Synchronous mode
Send Prefer: wait on a submit and the API holds the response until the job finishes, up to 60 seconds. Prefer: wait=N waits up to N seconds (1 to 60; larger values are capped at 60). It works on the capability and model endpoints and on workflow runs.
curl -X POST https://api.windpaint.ai/v1/generation/capabilities/image.generate \
-H "Authorization: Bearer $WINDPAINT_API_KEY" \
-H "Content-Type: application/json" \
-H "Prefer: wait=30" \
-d '{"prompt": "a lighthouse at dusk"}'
- Finished in time:
200with the full status object, outputs included. A job that endedfailed,nsfworcanceledalso returns200, so checkstatus. - Not finished in time:
202with the normal submit body. Pollstatus_urlas usual.
The job is created, held and queued exactly as without the header. When the server waited, the response has Preference-Applied: wait=N with the seconds it granted; if it’s missing, the server didn’t wait (for example, when it’s busy) and answered 202 straight away. Closing the connection while waiting doesn’t cancel the job. Invalid values such as wait=0 are ignored. Validation, auth and 402 errors return immediately.
Use it for images, which usually finish in seconds. Video usually takes longer than 60 seconds, so poll, stream or use a webhook.
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. Polling faster doesn’t make the job finish sooner, and every poll counts toward your rate limit.
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 markedcanceledand never runs.in_progress: the job is markedcanceledright 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:
project_idin the request body.- The
X-Windpaint-Projectheader, by id or slug. - 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
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, unless you send an Idempotency-Key header.
curl -X POST https://api.windpaint.ai/v1/generation/capabilities/image.generate \
-H "Authorization: Bearer $WINDPAINT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-123-hero" \
-d '{"prompt": "a lighthouse at dusk"}'
Send the same key with the same body again within 24 hours and you get the original response back, with the same request_id and the header Idempotent-Replayed: true. No second job is created. Generate the key once per logical request (a UUID works) and reuse it on every retry. See Idempotency for the rules.
Without a key, 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"
}
}
| Status | code | When |
|---|---|---|
402 | billing.insufficient_credits | Your organization’s available balance can’t cover credits_estimate. details has required and available. Nothing is held. |
409 | idempotency.key_reused, idempotency.in_progress | An Idempotency-Key was reused with a different request, or the first request with that key is still running. See Idempotency. |
422 | generation.asset_gone | An input asset has expired or was deleted. See Retention. |
422 | request.validation_failed | The request doesn’t fit the capability or model: an unknown capability or model, a missing prompt, the wrong number of assets in a slot, an unsupported resolution, aspect ratio, duration, quality, num_outputs or output_format, an unknown preset, or an input asset that isn’t in this project or is the wrong kind. Also returned for a capability with no model yet (“No model implements … yet”). The message says which. |
422 | input.* | A URL or data-URI input couldn’t be fetched, or an input file is the wrong format or too large. See Inputs. |
422 | moderation.input_blocked | The prompt or an input image was blocked by content moderation. No job is created. |
429 | rate_limit.requests, rate_limit.concurrency | Too many requests this minute, or too many jobs in flight. Wait Retry-After seconds. See Rate limits. |
503 | request.service_unavailable | The model is temporarily unavailable, or the requested tier has no price and can’t be sold. Retry later or pick another tier; GET /v1/generation/capabilities shows available: false for these. |
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.