Windpaint
Recipes

Batch product shots

Generate many product-shot variations across seeds and aspect ratios concurrently, with a cost check first, idempotency keys so retries never bill twice, and rate-limit backoff.

This recipe generates a grid of product shots, one prompt across several seeds and aspect ratios, with a few jobs in flight at once. It estimates the whole batch before submitting, polls with backoff, saves every image to disk, and can be re-run safely after a crash or a network error without paying for the same image twice.

The hard part of a batch is failure handling: if a POST times out after the API accepted it, a plain retry creates and bills a second job. The script avoids that with an Idempotency-Key per variation, saved to a manifest before the submit is sent. Retrying with the same key returns the job the first attempt created instead of making a new one. It also backs off on 429 when the batch hits your organization’s rate limits.

Prerequisites

  • An API key exported as WINDPAINT_API_KEY (API keys). The key needs to read billing; an admin’s or owner’s key does.
  • Python 3.10+ with httpx (pip install httpx).

The script

batch_shots.py
"""Product-shot variations across seeds and aspect ratios. Safe to re-run."""

import asyncio
import json
import os
import random
import sys
import uuid
from decimal import Decimal
from pathlib import Path

import httpx

API = os.environ.get("WINDPAINT_API_URL", "https://api.windpaint.ai").rstrip("/") + "/v1"
KEY = os.environ["WINDPAINT_API_KEY"]

PROMPT = (
    "studio product photo of a matte black ceramic coffee mug on a pale oak table, "
    "soft window light from the left, shallow depth of field, clean background"
)
SEEDS = [101, 202, 303]
ASPECT_RATIOS = ["1:1", "4:5", "9:16", "16:9"]
RESOLUTION = "1k"
CONCURRENCY = 4  # keep this at or below your tier's concurrent job limit
MAX_ATTEMPTS = 2  # a job that ends `failed` is free, so it gets one more try
SUBMIT_TRIES = 5

OUT = Path("shots")
MANIFEST = OUT / "manifest.json"
TERMINAL = {"completed", "failed", "nsfw", "canceled"}
RUNNABLE = {"pending", "queued"}


class APIError(Exception):
    def __init__(self, response: httpx.Response):
        self.status = response.status_code
        self.retry_after = float(response.headers.get("Retry-After", 0) or 0)
        try:
            body = response.json()
        except ValueError:
            body = {"error": response.text}
        error = body.get("error")
        if isinstance(error, dict):
            self.code, self.message = error.get("code"), error.get("message")
        else:  # 401/403 come back as {"status": false, "error": "Unauthorized", "code": ...}
            self.code, self.message = body.get("code"), body.get("message") or error
        super().__init__(f"{self.status} {self.code or ''} {self.message}".strip())


async def call(api: httpx.AsyncClient, method: str, path: str, **kwargs) -> dict:
    response = await api.request(method, path, **kwargs)
    if response.is_error:
        raise APIError(response)
    return response.json()


async def get_with_retry(api: httpx.AsyncClient, path: str, **kwargs) -> dict:
    """GETs are safe to retry on network errors, 429 and 5xx."""
    delay = 1.0
    for attempt in range(5):
        try:
            return await call(api, "GET", path, **kwargs)
        except (httpx.TransportError, APIError) as exc:
            retryable = not isinstance(exc, APIError) or exc.status == 429 or exc.status >= 500
            if not retryable or attempt == 4:
                raise
            wait = exc.retry_after if isinstance(exc, APIError) and exc.retry_after else delay
            await asyncio.sleep(wait + random.random())
            delay *= 2


def save(manifest: dict) -> None:
    MANIFEST.write_text(json.dumps(manifest, indent=2))


def load_manifest() -> dict:
    manifest = json.loads(MANIFEST.read_text()) if MANIFEST.exists() else {}
    for seed in SEEDS:
        for aspect in ASPECT_RATIOS:
            key = f"seed{seed}-{aspect.replace(':', 'x')}"
            manifest.setdefault(key, {"seed": seed, "aspect_ratio": aspect, "state": "pending", "attempts": 0})
    for entry in manifest.values():
        if entry["state"] in ("rejected", "unknown"):  # retried with the same Idempotency-Key
            entry.update(state="pending", error=None)
    return manifest


async def estimate_total(api: httpx.AsyncClient, todo: list[dict]) -> Decimal:
    total = Decimal(0)
    for aspect in sorted({e["aspect_ratio"] for e in todo}):
        body = {"capability": "image.generate", "prompt": PROMPT, "aspect_ratio": aspect, "resolution": RESOLUTION}
        estimate = (await call(api, "POST", "/generation/estimate", json=body))["data"]
        if estimate["credits"] is None:
            sys.exit(f"{estimate['model']} has no price at {RESOLUTION}")
        count = sum(1 for e in todo if e["aspect_ratio"] == aspect)
        total += Decimal(estimate["credits"]) * count
        print(f"  {aspect:>5}  {estimate['width']}x{estimate['height']}  {count} x {estimate['credits']} credits")
    return total


async def poll(api: httpx.AsyncClient, request_id: str) -> dict:
    delay = 1.5
    while True:
        status = await get_with_retry(api, f"/generation/requests/{request_id}/status")
        if status["status"] in TERMINAL:
            return status
        await asyncio.sleep(delay + random.uniform(0, 0.5))
        delay = min(delay * 1.5, 15)


async def download(api: httpx.AsyncClient, asset_id: str, path: Path) -> None:
    url = (await get_with_retry(api, f"/generation/assets/{asset_id}/url"))["data"]["url"]
    async with httpx.AsyncClient(timeout=300) as plain:  # signed URL: no Authorization header
        response = await plain.get(url)
        response.raise_for_status()
    path.write_bytes(response.content)


async def submit(api: httpx.AsyncClient, entry: dict, manifest: dict, stop: asyncio.Event) -> bool:
    """Submit, retrying with the same Idempotency-Key. Returns True when we hold a request_id."""
    if not entry.get("idempotency_key"):
        entry["idempotency_key"] = str(uuid.uuid4())
        save(manifest)  # persist the key before the first attempt, so a crash can't lose it
    body = {"prompt": PROMPT, "aspect_ratio": entry["aspect_ratio"], "resolution": RESOLUTION, "seed": entry["seed"]}
    headers = {"Idempotency-Key": entry["idempotency_key"]}
    for attempt in range(SUBMIT_TRIES):
        try:
            job = await call(api, "POST", "/generation/capabilities/image.generate", json=body, headers=headers)
        except httpx.TransportError as exc:
            entry.update(state="unknown", error=repr(exc))  # the job may exist; the same key finds it
            await asyncio.sleep(2 ** attempt + random.random())
            continue
        except APIError as exc:
            if exc.status == 429 or exc.code == "idempotency.in_progress" or exc.status >= 500:
                entry.update(state="unknown", error=str(exc))
                await asyncio.sleep((exc.retry_after or 2 ** attempt) + random.random())
                continue
            entry.update(state="rejected", error=str(exc))  # 4xx: nothing was created or billed
            if exc.code == "billing.insufficient_credits":
                stop.set()
            return False
        entry.update(request_id=job["request_id"], state="queued", attempts=entry["attempts"] + 1, error=None)
        return True
    return False  # still unknown: the next run retries with the same key


async def run_one(api, sem, key, manifest, stop) -> None:
    entry = manifest[key]
    async with sem:
        while True:
            if not entry.get("request_id"):
                if stop.is_set():
                    return
                ok = await submit(api, entry, manifest, stop)
                save(manifest)  # persist the request_id before doing anything else
                if not ok:
                    print(f"{key}: {entry['state']} ({entry['error']})")
                    return
            status = await poll(api, entry["request_id"])
            if status["status"] == "completed":
                path = OUT / f"{key}.png"
                await download(api, status["outputs"][0]["id"], path)
                entry.update(state="completed", file=str(path), credits=status["credits"]["actual"])
                save(manifest)
                print(f"{key}: saved {path}")
                return
            if status["status"] == "failed" and entry["attempts"] < MAX_ATTEMPTS:
                print(f"{key}: failed ({status['error_code']}), trying once more")
                entry.pop("request_id")
                entry.pop("idempotency_key")  # a new attempt needs a new key; the old one replays the failed job
                continue
            entry.update(state=status["status"], error=status["error"])
            save(manifest)
            print(f"{key}: {status['status']} ({status['error']})")
            return


async def main() -> None:
    OUT.mkdir(exist_ok=True)
    manifest = load_manifest()
    async with httpx.AsyncClient(base_url=API, headers={"Authorization": f"Bearer {KEY}"}, timeout=60) as api:
        todo = [e for e in manifest.values() if e["state"] == "pending" and not e.get("idempotency_key")]
        if todo:
            print(f"{len(todo)} new image(s) at {RESOLUTION}:")
            total = await estimate_total(api, todo)
            available = Decimal((await call(api, "GET", "/billing/balance"))["data"]["available"])
            print(f"total {total} credits, {available} available")
            if total > available:
                sys.exit("not enough credits; top up in Settings -> Billing or shrink the batch")
            if input("Submit? [y/N] ").lower() != "y":
                sys.exit("nothing submitted")

        sem, stop = asyncio.Semaphore(CONCURRENCY), asyncio.Event()
        keys = [k for k, e in manifest.items() if e["state"] in RUNNABLE]
        await asyncio.gather(*(run_one(api, sem, k, manifest, stop) for k in keys))

    states: dict[str, int] = {}
    for entry in manifest.values():
        states[entry["state"]] = states.get(entry["state"], 0) + 1
    spent = sum(Decimal(e["credits"]) for e in manifest.values() if e.get("credits"))
    print(f"done: {states}, {spent} credits charged in total")
    if states.get("unknown") or states.get("rejected"):
        print("re-run the script within 24 hours to retry unknown and rejected variations")


if __name__ == "__main__":
    asyncio.run(main())

Run it

export WINDPAINT_API_KEY=aak_...
python batch_shots.py
12 new image(s) at 1k:
    1:1  1024x1024  3 x 0.08 credits
   16:9  1024x576  3 x 0.08 credits
    4:5  816x1024  3 x 0.08 credits
   9:16  576x1024  3 x 0.08 credits
total 0.96 credits, 42.5 credits available
Submit? [y/N] y
seed101-1x1: saved shots/seed101-1x1.png
seed202-1x1: saved shots/seed202-1x1.png
...
done: {'completed': 12}, 0.96 credits charged in total

shots/ ends up with one PNG per variation and manifest.json, which records each variation’s state, idempotency_key, request_id, file and credits. Run the script again and it does nothing new: completed variations are skipped, and anything still queued is polled rather than resubmitted.

How it handles failures

What happenedStateBilled?What the script does
Submit returned 202queuedHeldSaves the request_id immediately, then polls it
Network error, timeout or 5xx on submitunknownMaybeRetries with the same Idempotency-Key. If the first attempt created a job, the retry returns that job’s request_id with Idempotent-Replayed: true; nothing is billed twice.
409 idempotency.in_progressunknownHeld by the first attemptWaits Retry-After (1 second) and retries with the same key
429 on submitunknownNoWaits Retry-After and retries with the same key
Other 4xx on submit (422, 402, …)rejectedNoRecords the error. On 402 billing.insufficient_credits it stops submitting the rest of the batch. Retried on the next run with the same key.
Job ended failedfailedNo, the hold is releasedRetries once with a new key, then records the error
Job ended nsfwnsfwNoRecords it. Change the prompt if it keeps happening. See Moderation.
Script killed mid-batchqueued, pending or unknownOnly for created jobsOn the next run, polls saved request_ids and retries the rest with their saved keys

Two limits to keep in mind:

  • Keys last 24 hours. A retry with the same key more than 24 hours after the first attempt runs as a new request. Re-run an interrupted batch the same day.
  • A failed request stores nothing. A 4xx or 5xx answer isn’t saved under the key, so a retry after fixing the cause runs normally. In rare cases a 5xx comes after the job was already created; the key is released then, and a retry can create a second job. See Idempotency.

GETs (status, asset URL) are safe to retry, so get_with_retry() retries them on network errors, 429 and 5xx, waiting Retry-After when the API sends one. CONCURRENCY keeps the number of jobs in flight at or below your concurrent job limit (5 on tier 1); a submit above it is refused with 429 rate_limit.concurrency. It also keeps a large batch from holding most of your balance at once.

Adjusting the batch

  • More variety: add prompts as another dimension of the grid, keyed into the manifest the same way.
  • Another model: send "model": "flux-2-klein-4b" with each request. The estimate step prices it before anything runs.
  • Different sizes: any of 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 21:9, 4:5, 5:4. At 1k the long edge is 1024 px and the short edge follows the ratio, rounded to a multiple of 16.
  • Fewer requests: for image.generate, num_outputs (up to 4) returns several images from one job, priced per image. Use separate jobs with separate seeds when you need to reproduce a specific image later. See Multiple outputs.
  • No polling: pass webhook_url on each submit and let a receiver download the results. Keep the manifest either way, so you know which jobs to expect. See Webhook receiver.

Next steps