Images
Generate images with image.generate: resolution and aspect ratio, pixel sizes, seeds, prompting and reading the output.
image.generate turns a text prompt into up to four images. It runs on z-image-turbo by default, or flux-2-klein-4b if you name it, both at 1k: 0.08 credits per image on z-image-turbo and 0.10 on flux-2-klein-4b (read current prices from the catalog). Most images finish within a few seconds of being picked up.
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 ceramic teapot on a linen tablecloth, soft window light"}'
That’s a 1024 × 1024 image: model, resolution and aspect_ratio all have defaults. Poll the returned status_url until status is completed, then read outputs[0]. The overview has polling loops. Images usually finish within seconds, so you can also send Prefer: wait and get the finished job in the submit response; see synchronous mode.
Parameters that matter
| Field | Values | Default | Notes |
|---|---|---|---|
prompt | string | none | Required. |
resolution | 1k | 1k | Sets the long edge: 1024 px. |
aspect_ratio | 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 21:9, 4:5, 5:4 | 1:1 | Sets the short edge from the long edge. |
seed | integer | random | Same seed + same request = same image. |
num_outputs | 1 to 4 | 1 | Images in one job. Billed per image delivered. |
output_format | png, jpeg, webp | png | Re-encoded on the server. |
output_quality | 1 to 100 | 90 | jpeg and webp only. |
preset | preset slug | none | A Windpaint preset such as product-shot. |
model | z-image-turbo, flux-2-klein-4b | z-image-turbo | Both take the same fields. |
webhook_url | https URL | none | See Webhooks. |
image.generate takes no input assets, no duration and no quality; sending inputs, duration or quality returns 422. There is no negative prompt field.
Pixel sizes
The 1k tier fixes the long edge and the aspect ratio sets the other, rounded to the nearest multiple of 16. Portrait ratios swap the edges.
| Aspect ratio | 1k |
|---|---|
1:1 | 1024 × 1024 |
4:3 / 3:4 | 1024 × 768 / 768 × 1024 |
3:2 / 2:3 | 1024 × 688 / 688 × 1024 |
16:9 / 9:16 | 1024 × 576 / 576 × 1024 |
21:9 | 1024 × 432 |
5:4 / 4:5 | 1024 × 816 / 816 × 1024 |
Because of the rounding, some sizes aren’t the exact ratio (1024 × 688 is 1.488:1, not 1.5:1). If you need an exact size, crop afterwards. POST /v1/generation/estimate returns width and height for any request without running it; see Models.
The price depends only on the model and tier, not the aspect ratio: a 1k 21:9 image costs the same as a 1k 1:1 one.
Seeds
Pass a seed to make a result reproducible. The same prompt, model, resolution, aspect ratio and seed give you the same image, so you can regenerate one later or change one setting and compare.
The API doesn’t report the seed it picked when you leave it out, so a result made without a seed can’t be reproduced. If you might want an image again, always send a seed.
To get variations of one prompt, set num_outputs (up to 4) on one request, or submit the same request several times with different seeds when you want to know each image’s seed. Each request is a separate job, billed separately:
import os
import requests
API = "https://api.windpaint.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['WINDPAINT_API_KEY']}"}
body = {"prompt": "a ceramic teapot on a linen tablecloth, soft window light", "aspect_ratio": "4:5"}
jobs = []
for seed in (1, 2, 3, 4):
resp = requests.post(
f"{API}/generation/capabilities/image.generate",
headers=HEADERS,
json={**body, "seed": seed},
)
resp.raise_for_status()
jobs.append(resp.json()["request_id"])
Record each request_id as soon as you get it, and send an Idempotency-Key header with each submit so a retry after a timeout doesn’t create and bill a second job; see Retries and double billing.
Prompting
z-image-turbo responds to plain descriptive prompts. Some things that tend to help:
- Describe the subject first, then the setting, then lighting and style: “a ceramic teapot on a linen tablecloth, soft window light, 35mm photo”.
- Name the medium you want (“watercolor”, “studio product photo”, “flat vector illustration”); without it the model picks one.
- Say what should be in the frame rather than what shouldn’t. There’s no negative prompt.
- Pick the aspect ratio for the composition instead of describing it in words: a wide landscape reads better at
16:9or21:9than at1:1. - Keep a seed fixed while you iterate on wording, so changes in the image come from the prompt.
A prompt that the content filter blocks is rejected at submit with 422 moderation.input_blocked. If the output is blocked, or the model refuses, the job ends with status nsfw, no output, and no charge. See Moderation.
Output
A completed job has one entry in outputs per image (and the same entries in 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
}
The format is output_format: PNG by default, or JPEG or WebP re-encoded on the server. JPEG has no transparency, so transparent areas become white. Use content_type, not an assumed extension, when you save the file.
url is the asset’s API URL. Fetching it needs your API key and answers with a redirect to a short-lived download link; Assets covers how to download it or hand it to a browser. The id can go straight into another job’s inputs, for example as the start_frame of a video.
End to end
Submit, wait, and save the image to disk.
The curl version names the file .png for brevity; check .outputs[0].content_type if you need the right extension every time. The CLI picks the extension for you when -o is a directory.