Concepts
The core objects in Windpaint: organizations, projects, capabilities, models, jobs, assets, products, and credits.
A handful of objects cover everything in Windpaint. Once you have these, the rest of the docs are reference.
Organizations
Your organization is the account. It owns the credit balance, the team, the API keys, and the account webhooks. Each user belongs to one organization, and one is created for you when you sign up.
Members have one of four roles: owner, admin, member (can generate, and read projects, billing, and keys), or read_only. An API key acts in its creator’s organization with its creator’s role, or with a narrower role you assign to the key. See Organizations and projects and API keys.
Projects
A project groups work inside an organization. Every job, asset, and product run belongs to exactly one project. Each organization has a default project (named “Default”, slug default) that can’t be archived, and you can create as many more as you need.
A request goes to a project chosen in this order:
project_idin the request body.- The
X-Windpaint-Projectheader, with a project id or slug. - The organization’s default project.
Credits are not per project. All projects spend from the organization’s balance.
Capabilities and models
A capability is a kind of task, named <medium>.<verb>. You submit work to a capability, not to a model:
| Capability | Produces | Live model |
|---|---|---|
image.generate | An image from a prompt | z-image-turbo |
video.generate | A 5 second clip from a start frame and a prompt | wan-2.2-i2v |
Each capability declares its input slots: named places for media, each with the kinds it accepts and how many. video.generate, for example, has a start_frame slot that takes one image.
A model implements one or more capabilities. If you leave model out, Windpaint uses the capability’s first available model. Name one when you want to pin the output style. Each model offers its own resolution tiers and durations, and each combination has a price. Model ids are stable slugs; there’s no way to pin an older version of a model.
GET /v1/generation/capabilities lists every capability with its slots, models, tiers, and current prices. Capabilities that don’t have a model yet (image.edit, mask.segment, media.upscale, audio.speech, video.lipsync, text.llm) appear with an empty models list, and submitting to them returns 422. See Models.
Jobs
Submitting to a capability creates a job. The API calls it a request, so its id is request_id and you poll it at /v1/generation/requests/{id}/status. Every job is asynchronous: the submit returns 202 with the id straight away, and you poll or wait for a webhook. There is no synchronous mode.
A job moves through these statuses:
| Status | Meaning |
|---|---|
queued | Accepted and waiting for capacity. |
in_progress | Rendering. |
completed | Done. Outputs are in outputs and stored as assets. |
failed | Something went wrong; see error. Not charged. |
nsfw | The output was flagged as unsafe and not returned. Not charged. |
canceled | You canceled it before it finished. Not charged. |
The last four are terminal. Each job also records its source: studio (the dashboard), api, or workflow (a step of a product run).
Assets
An asset is a stored file in a project: either a file you uploaded or an output of a job. Every asset has an id, a kind (image, video, audio, mask, or text), and a url that needs your API key and redirects to a signed download link valid for 15 minutes.
You pass assets to jobs by id. A job’s output can be the next job’s input with no download in between. Inputs must be assets in the same project; external URLs are rejected. Assets don’t expire and there’s no delete endpoint today. See Assets.
Products and runs
A product is a pre-built pipeline that chains several capability steps, plus free steps like resizing an image or pulling a frame from a video, behind one call. You fill in the product’s inputs; a run executes the steps in order and returns each named output. Runs have their own statuses (queued, running, completed, failed, canceled) and each capability step inside a run is an ordinary job you can inspect. Windpaint defines the products; you can’t create your own yet. See Products.
Credits and holds
Windpaint bills in prepaid credits at the organization level. Each output has a fixed price in credits that depends on the model and tier, and the price is set when you submit.
When you submit a job, its estimate is held from your available balance. If you don’t have enough, the submit fails with 402. When the job completes, the hold is captured. If it fails, is flagged nsfw, or is canceled, the hold is released in full, so failures are free. Your balance shows available and held separately. See Pricing.