Windpaint
Commands

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 1k
windpaint run image.generate "a lighthouse at dusk" -m flux-2-klein-4b -o ./out/

capabilities

windpaint capabilities
windpaint capabilities get video.generate

The example below shows video.generate, which is coming soon: wan-2.2-i2v is listed with its planned price but isn’t available yet.

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  MAX OUTPUTS  FORMATS  CREDITS     LICENCE
wan-2.2-i2v  no         480p         -          5s         1                     480p/5s:4   Apache-2.0

MAX OUTPUTS is the most images one request can return (-n), and FORMATS the output formats you can ask for with --output-format; it’s empty for models whose format isn’t selectable.

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
flux-2-klein-4b  image.generate  yes        1k:0.1
wan-2.2-i2v      video.generate  no         480p/5s:4

estimate

windpaint estimate image.generate "a lighthouse at dusk" -r 1k
windpaint estimate video.generate -p "slow dolly in" -i start_frame=./frame.png
windpaint estimate image.generate "a lighthouse at dusk" -n 4 --output-format webp

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

With -n above 1 the output adds Outputs 4 x 0.08 credits, and with --output-format a Format line; Credits is then the total for every output.

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 1k -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
windpaint run image.generate "a lighthouse at dusk" -n 4 --output-format webp --output-quality 85 -o ./out/
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.

While waiting, run first asks the API to hold the submit until the job finishes, for up to --timeout or 60 seconds, whichever is shorter (Prefer: wait). Most images come back in that one call. If the job is still running after that, run polls until --timeout. Because the held submit and the polling are timed separately, the total wait can reach --timeout plus 60 seconds. --no-wait sends no wait preference.

The progress line on stderr shows the job’s place in the queue (3 ahead in queue, next in queue) and, once it’s running, the percentage the model reports (42%) when it reports one.

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.

FlagDescription
-p, --prompt <text>Prompt. You can also give it as positional arguments after the capability; not both. - reads it from stdin.
-i, --input <slot=value>Fill an input slot. Repeatable; comma-separate several values for one slot (not URLs or data: URIs). See Input values.
-m, --model <model>Model id. Default: the capability’s first available model.
-r, --resolution <tier>Resolution tier, e.g. 1k, 480p. Default: the model’s default tier.
-a, --aspect-ratio <ratio>e.g. 16:9, 9:16, 1:1. Default: 16:9 for video, 1:1 otherwise.
-d, --duration <seconds>Clip length for video. Only sent when you pass it.
--quality <tier>Quality tier. No current model has quality tiers, so any value is rejected today.
-n, --num-outputs <n>Images to generate in one request, 1 to the model’s max outputs (4 for z-image-turbo). Billed per output delivered. Image models only.
--output-format <format>Image output format: png (default), jpeg or webp. Image models only.
--output-quality <1-100>Encoding quality for --output-format jpeg or webp. Default 90.
--seed <int>Seed, for repeatable results.
--webhook-url <url>HTTPS URL the API calls when the job finishes. Deliveries are signed and retried. See Webhooks.
-o, --output <path>Download outputs to this file or directory. See Output files.
--forceOverwrite existing files when downloading.
--no-waitReturn after submitting.
--timeout <duration>How long to wait, e.g. 30s, 10m. Default 15m; 0 waits forever.

Live models today are z-image-turbo (the default) and flux-2-klein-4b for image.generate, both 1k. wan-2.2-i2v for video.generate (480p, 5 seconds, needs a start_frame) is coming soon; the video examples on this page show how it will work. A video request makes one clip; an image request makes one image, or up to 4 with -n. Run windpaint capabilities for the current list.

How run ends:

OutcomeExit codestdout
Job completed0Final status
Job failed, nsfw or canceled9Final status, with error
Still running after --timeout10Last status. Continue with windpaint status <id> --wait.
Ctrl-C130Nothing. The job keeps running; cancel it with windpaint cancel <id>.

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

run sends a random Idempotency-Key with every submit and upload. If the call fails with a network error, or the API reports the first attempt still in progress, it retries the same call with the same key, up to 3 attempts one second apart, so a retry never creates or bills a second job. Running the whole command again uses a new key and does create a new job; if a run failed with a network error, check windpaint requests first.

Input values

-i slot=value accepts these forms of value:

ValueExampleWhat happens
Local file path-i start_frame=./frame.pngUploaded as an asset first, then its id is sent. Used when the file exists.
@path-i [email protected]Always treated as a local file, even if the name looks like an id or URL.
Asset id-i start_frame=8e1f4c2a-6b7d-4e3f-9a1c-2d5e8f0b7c64Sent as is. Use outputs of earlier runs or ids from windpaint upload.
Asset URL-i start_frame=https://api.windpaint.ai/v1/generation/assets/8e1f4c2a-6b7d-4e3f-9a1c-2d5e8f0b7c64/contentSent as is.
Public https:// URL-i start_frame=https://example.com/frame.pngSent as is. The API fetches the file at submit and stores it as a new asset.
data: URI-i start_frame=data:image/png;base64,iVBOR...Sent as is. The API decodes it (up to 5 MB) and stores it as a new asset.

Several values for one slot:

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

Values starting with https://, http:// or data: are never split on commas, since they can contain them. Repeat -i to pass several.

Local files are uploaded if they’re 200 MiB or smaller; the CLI recognises .png, .jpg, .jpeg, .webp, .mp4, .mov, .webm, .mp3, .wav, .m4a and .ogg. The API then applies the per-kind limits (images 20 MB, video 200 MB and 60 s, audio 25 MB and 5 min) and checks the format from the file’s bytes; see Input requirements. A path that doesn’t exist, isn’t an id and isn’t a URL or data: URI fails with exit code 2 before anything is sent. The same file used twice in one command is uploaded once. Uploads are free.

Asset ids must be in the project you’re running in. A URL the API can’t fetch (not https, a private address, an error status, a timeout) is rejected with input.fetch_failed (exit code 6).

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:

-o valueSaved as
A directory: existing, or ending in /<dir>/<asset-id>.<ext>. A new directory is created.
A file path, one outputExactly that path, e.g. clip.mp4
A file path, several outputs<name>-1.<ext>, <name>-2.<ext>, …

The extension comes from the output’s content type (.png, .mp4, …). An existing file is never overwritten unless you pass --force; without it run checks the target before submitting and exits with code 2, so nothing is billed. If the job completes but the download fails, the final status is still printed and the command exits with code 1 and the request id; download with windpaint status <request-id> -o <path>. 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.

FlagDescription
-w, --waitWait until the request finishes, with the same exit codes as run.
--timeout <duration>How long to wait. Default 15m; 0 waits forever.
-o, --output <path>Download outputs, with the same naming as run.
--forceOverwrite existing files.

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
FlagDescription
-n, --limit <n>Maximum rows, 1–200. Default 20.
--run <run-id>Only the generation steps of this workflow run.

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

Next