Rate limits and bulk generation
The request limits of the Cheapest Imagen API (300 a minute, 50 at once), what a 429 means, and how to generate thousands of images with retries that never charge twice.
The limits
| Limit | Value | Error when exceeded |
|---|---|---|
| Requests per minute, per account | 300 | 429 rate_limit_exceeded |
| Requests in progress, per account | 50 | 429 concurrency_limit_exceeded |
Images per request (n) | 10 at 1K, 4 at 2K, 2 at 4K | 400 invalid_value |
| Refused prompts per hour | 10 | 429 moderation_paused for an hour |
| Time for one request | 420 seconds | 504 upstream_timeout, not charged |
The limits are per account, shared by all its API keys and the site. There are no usage tiers.
A request does not have to hold a connection open for that long: sent with async: true it answers at once with a task you read later. See Synchronous and asynchronous requests.
How many images that is
With 50 requests in progress and 10 images in each, up to 500 1K images are being made at once. A 1K image usually takes 20 to 40 seconds, so the limits leave room for tens of thousands of images an hour on one account. If you need more, write to support@cheapestimagen.com with your volume.
Retry without paying twice
- On
429, wait and send the request again; double the wait each time. - On
502and504the request was not charged; send it again. - Add an
Idempotency-Keyheader to each job. If a request with that key is still running or already succeeded, a repeat answers409 idempotency_key_in_useand nothing is generated or charged again. After a failure the key can be used again.
import asyncio
from openai import AsyncOpenAI, RateLimitError, APIStatusError
client = AsyncOpenAI(base_url="https://api.cheapestimagen.com/v1", api_key="YOUR_KEY")
gate = asyncio.Semaphore(50) # requests in progress: the account limit
async def make(prompt: str, key: str):
async with gate:
for attempt in range(6):
try:
r = await client.images.generate(
model="nano-banana-2.1",
prompt=prompt,
size="1024x1024",
response_format="url",
extra_headers={"Idempotency-Key": key},
)
return r.data[0].url
except RateLimitError:
await asyncio.sleep(2 ** attempt)
except APIStatusError as e:
if e.status_code not in (502, 504):
raise
await asyncio.sleep(2 ** attempt)
async def main(prompts):
return await asyncio.gather(*(make(p, f"job-{i}") for i, p in enumerate(prompts)))Keep the results
A link from response_format: "url" works for 72 hours. Copy the files to your own storage as they arrive.
What a failure costs
Nothing. You pay only for images you receive; when a request for several images returns fewer, only those are charged. The stable channels (ids ending in -1k, -2k, -4k) are the exception: they charge for an image refused for its content. Every code is in Errors.
Synchronous and asynchronous requests
Two ways to call the image API. Wait for the image in one request, or send async true, get a task id at once, and read one or many tasks with a single polling request or a webhook.
Errors
Every HTTP status and error code the Cheapest Imagen API returns, what each one means, whether it was charged and what to do next.