Build a Reliable Production Integration
A reliable integration sends each job once, records its generation_id before waiting, collects the result by polling or webhook, downloads the files within 24 hours, and checks what it was charged. This guide walks through that lifecycle and links to the page that covers each step in detail.
1. Choose keys and a workspace
Keys can’t be scoped: a key can call every endpoint its workspace can use and spend that workspace’s balance. Use a separate API team for each environment that needs its own balance or people. If you have an Ideogram subscription, a request uses your monthly credits only when they cover all of it; otherwise the whole request is charged to your API balance. See Authentication and API keys and API Setup.
2. Quote the request
Send the request with dry_run=true to get its price without running it. A quote doesn’t check your balance or your in-flight requests, so the real request can still be rejected. See Price quotes.
3. Submit asynchronously and record the ID
Most image endpoints wait for the result by default. For production jobs, set async or supply a webhook_url: the request returns a generation_id as soon as it is accepted. Store that ID with your own job record before you wait for anything. Video, tool and SVG endpoints, Replace Background, Remove Objects and Reframe with Nano Banana 2 always run asynchronously.
A synchronous request that waits 265 seconds without finishing returns 503. The generation keeps running and is billed when it completes, but the 503 has no generation_id, so you can’t collect the result. That is the main reason to submit production jobs asynchronously.
4. Poll with a deadline, or receive a webhook
Poll GET /v2/generations/{generation_id} every few seconds until status is completed or failed. Set your own deadline. When it passes, keep the ID and check again later rather than resubmitting. Polling is rate limited: on a 429, wait for the seconds in Retry-After. See Rate limits.
With a webhook_url, Ideogram sends the result when the generation completes. Verify the signature, process each generation_id once, and keep polling as a fallback: a failed generation sends no webhook, and a delivery can be dropped after its retries. See Webhooks.
5. Retry without paying twice
The API takes no idempotency key, and every request you send is a new, billed generation. A 429 was rejected before it ran, so retry it after a wait. A 402 also didn’t run, but it fails again until you add credits. Don’t resend a request that timed out or whose response you lost: poll its generation_id instead. See Idempotency and safe retries.
6. Store the files and the metadata
Result links expire after 24 hours, and each poll returns fresh ones. Download every file into your own storage, then keep the generation_id, prompt, seed, resolution, is_image_safe and any asset_id. See Responses and metadata.
7. Reconcile cost
Compare your quotes with what you were charged: usage_cost_usd_micros on a completed generation (when the request uses variable usage-based pricing), GET /v2/account/usage for a date range and GET /v2/account/invoices for invoices.
8. Handle failures
See Errors and billing for the full table.
9. What the API doesn’t offer
- No cancel operation. An accepted request runs to completion. See Cancel a request.
- No idempotency key. Record the
generation_idand poll before resubmitting. - No scoped keys. Separate environments with separate API teams.
- No batch endpoint. Send requests with bounded concurrency.
- No official SDK packages. Use any HTTP library, or generate a client from the OpenAPI specification. See SDKs and client libraries.
A complete example
This Python example quotes a request, submits it asynchronously, records the ID, polls with a deadline and stores the files. JobStore stands in for your own database; replace its methods with real writes.
Run it with IDEOGRAM_API_KEY set. It prints the quoted price, then the final status and what it stored, and saves each image as <generation_id>-<index>.png.
Moving from v1
The v1 API keeps working. The v1 to v2 endpoint table in API Overview lists each v2 equivalent.