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
"""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 happened | State | Billed? | What the script does |
|---|---|---|---|
Submit returned 202 | queued | Held | Saves the request_id immediately, then polls it |
Network error, timeout or 5xx on submit | unknown | Maybe | Retries 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_progress | unknown | Held by the first attempt | Waits Retry-After (1 second) and retries with the same key |
429 on submit | unknown | No | Waits Retry-After and retries with the same key |
Other 4xx on submit (422, 402, …) | rejected | No | Records 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 failed | failed | No, the hold is released | Retries once with a new key, then records the error |
Job ended nsfw | nsfw | No | Records it. Change the prompt if it keeps happening. See Moderation. |
| Script killed mid-batch | queued, pending or unknown | Only for created jobs | On 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
4xxor5xxanswer isn’t saved under the key, so a retry after fixing the cause runs normally. In rare cases a5xxcomes 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. At1kthe 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_urlon each submit and let a receiver download the results. Keep the manifest either way, so you know which jobs to expect. See Webhook receiver.