Generation commands

Command reference for capabilities, models, estimate, run, status, cancel and requests.

These commands cover the generation loop: find a capability, check what it costs, run it, and collect the outputs. See Generation overview for how capabilities, models and jobs fit together.

windpaint capabilities get image.generate
windpaint estimate image.generate "a lighthouse at dusk" -r 2k
windpaint run image.generate "a lighthouse at dusk" -r 2k -o ./out/

capabilities

windpaint capabilities
windpaint capabilities get video.generate

capabilities (alias caps, or capabilities list) lists every capability with the models that serve it and the cheapest price:

CAPABILITY      OUTPUT  MODELS         CREDITS    DESCRIPTION
image.generate  image   z-image-turbo  from 0.08  Text to image.
video.generate  video   wan-2.2-i2v    from 4     Prompt, optionally with a start frame and an end frame, to a…
image.edit      image   -              -          Reference images plus instruction to image. Covers edit, in…
...

Capabilities with no model yet are listed with - in MODELS; running them fails with exit code 6.

capabilities get <capability> (alias show) shows what you need to run one: whether the prompt is required, the input slots to fill with -i, the aspect ratios, and each model’s resolutions, durations and per-tier prices:

Capability     video.generate
Description    Prompt, optionally with a start frame and an end frame, to a video clip.
Output         video
Prompt         required
Aspect ratios  1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 21:9, 4:5, 5:4

Inputs (-i slot=file|asset-id):
SLOT         KINDS  COUNT  DESCRIPTION
start_frame  image  0-1    First frame.
end_frame    image  0-1    Last frame, for first/last-frame interpolation.

Models:
MODEL        AVAILABLE  RESOLUTIONS  QUALITIES  DURATIONS  CREDITS     LICENCE
wan-2.2-i2v  yes        480p         -          5s         480p/5s:4   Apache-2.0

The slot counts are the capability’s limits. A model can be stricter: wan-2.2-i2v needs exactly one start_frame and no end_frame. With --json you get the API’s capability object, including each model’s own inputs limits. Prices change; read them from here or from Models rather than hardcoding them.

models

windpaint models

Lists each model with the capabilities it serves, whether it’s available, and its prices as tier:credits:

MODEL          CAPABILITY      AVAILABLE  CREDITS (tier:credits)
z-image-turbo  image.generate  yes        1k:0.08 2k:0.3
wan-2.2-i2v    video.generate  yes        480p/5s:4

estimate

windpaint estimate image.generate "a lighthouse at dusk" -r 2k
windpaint estimate video.generate -p "slow dolly in" -i start_frame=./frame.png

Prices a request without running it. estimate takes the same flags as run (except --seed and --webhook-url) and validates them, so a wrong slot, resolution or duration fails here first. Local files are not uploaded for an estimate, and nothing is charged.

Capability  image.generate
Model       z-image-turbo
Credits     0.3
Output      2048x2048
Available   yes
Balance     187.4 available, 0 held

Credits reads no price for this tier (cannot be submitted) when the model has no price for what you asked. Balance is your organization’s balance; the JSON adds it as available_credits and held_credits.

run

windpaint run image.generate "a lighthouse at dusk, film grain" -o ./out/
windpaint run image.generate -p "a lighthouse at dusk" -r 2k -a 16:9 --seed 42 -o lighthouse.png
windpaint run video.generate -p "slow dolly in, golden hour" -i start_frame=./frame.png -o clip.mp4
windpaint run video.generate -p "slow dolly in" -i start_frame=./frame.png --no-wait
echo "a lighthouse at dusk" | windpaint run image.generate -p - -o ./out/

run <capability> [prompt] uploads any local input files, submits the job, waits for it with progress on stderr, and prints the final status. With -o it downloads the outputs. With --no-wait it prints the submitted request and returns immediately.

Uploading ./frame.png (412.3 KiB)...
Uploaded ./frame.png -> 8e1f4c2a-6b7d-4e3f-9a1c-2d5e8f0b7c64
Submitted 3c9a7e21-4f5b-4d6c-8e9a-1b2c3d4e5f60 (video.generate, estimate 4 credits)
3c9a7e21-4f5b-4d6c-8e9a-1b2c3d4e5f60 completed in 2m41s
Saved clip.mp4
Request     3c9a7e21-4f5b-4d6c-8e9a-1b2c3d4e5f60
Status      completed
Capability  video.generate
Model       wan-2.2-i2v
Credits     4 charged

OUTPUT                                TYPE       SIZE  LOCATION
d41e8b0c-2a3f-4c5d-9e6f-7a8b9c0d1e2f  video/mp4  5.0s  /Users/you/clip.mp4

The first lines go to stderr; the table is stdout. With --json, stdout is the API’s request status object plus downloads when files were saved.

Live models today are z-image-turbo for image.generate (1k, 2k) and wan-2.2-i2v for video.generate (480p, 5 seconds, needs a start_frame). One request makes one image or one clip. Run windpaint capabilities for the current list.

How run ends:

Credits are held when the job is submitted and charged only when it completes. Failed, nsfw and canceled jobs cost nothing. See Pricing.

Input values

-i slot=value accepts four forms of value:

Several values for one slot:

-i images=./front.png,./side.png
-i images=./front.png -i images=./side.png

Local files must be PNG, JPEG, WebP, MP4, MP3 or WAV, and 50 MiB or smaller. A path that doesn’t exist, isn’t an id and isn’t a URL fails with exit code 2 before anything is sent. The same file used twice in one command is uploaded once. Uploads are free.

Inputs must be in the project you’re running in. External URLs are rejected by the API (exit code 6); upload the file instead.

Output files

Without -o, run doesn’t download anything; the LOCATION column shows each output’s API URL, which needs your key to fetch. With -o:

The extension comes from the output’s content type (.png, .mp4, …). An existing file is never overwritten unless you pass --force; without it the command exits with code 2 after the job has finished. Download again with windpaint download <asset-id>.

status

windpaint status 3c9a7e21-4f5b-4d6c-8e9a-1b2c3d4e5f60
windpaint status 3c9a7e21-4f5b-4d6c-8e9a-1b2c3d4e5f60 --wait -o clip.mp4

Shows one request: status, capability, model, credits, error and outputs. Status is one of queued, in_progress, completed, failed, nsfw or canceled. Finds the request anywhere in your organization, whatever project is selected.

Without --wait, status exits 0 whatever the job’s status. -o without --wait downloads only if the job has already completed; if it’s still running, the command exits with code 10.

cancel

windpaint cancel 3c9a7e21-4f5b-4d6c-8e9a-1b2c3d4e5f60

Cancels a request that hasn’t finished and prints its status. A render that’s already running isn’t interrupted, but its output is discarded and the held credits are released. Canceling a finished request returns it unchanged. cancel exits 0 either way; check Status in the output.

requests

windpaint requests
windpaint requests -n 100 --json | jq -r '.[] | select(.status=="failed") | .request_id'
windpaint requests --run 9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f

Lists generation requests in the selected project, newest first. Alias jobs; requests list also works.

REQUEST                               STATUS     CAPABILITY      MODEL          CREDITS  OUTPUTS  CREATED
3c9a7e21-4f5b-4d6c-8e9a-1b2c3d4e5f60  completed  video.generate  wan-2.2-i2v    4        1        2026-10-04 14:12
0b6e2f4a-91c3-4d8e-a5f7-3c2d1e0f9a8b  completed  image.generate  z-image-turbo  0.08     1        2026-10-04 14:09

CREDITS is the charged amount once a job completes, otherwise the estimate.

Next