> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://developer.ideogram.ai/v2/llms.txt
> - v1: https://developer.ideogram.ai/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.ideogram.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.ideogram.ai/_mcp/server.

> The Ideogram API takes no idempotency key. Retry without paying twice: record the generation ID, poll before resubmitting and make webhook handlers idempotent.

The Ideogram API doesn't accept an idempotency key. Every request you send starts a new generation, and each one is billed. Sending the same request twice, for example after a timeout, creates two generations and two charges.

## Retry without paying twice

1. **Send long or important jobs asynchronously.** Set `async` or supply a `webhook_url`. The request returns a `generation_id` as soon as it is accepted.
2. **Record the `generation_id` before you wait.** Store it with your own job record as soon as the request returns.
3. **Poll before you resubmit.** If you lose track of a job, poll [`GET /v2/generations/{generation_id}`](/v2/api-reference/generations/get-generation). Resubmit only when its `status` is `failed`.
4. **Retry only what didn't run.** A `429` or a `402` means the request was rejected before it ran, so retrying it can't double-charge; a `402` keeps failing until you add credits. A timeout on a synchronous request doesn't stop the work; see [Errors and billing](/v2/ideogram-api/errors).

If a submission fails before you receive a `generation_id`, you can't tell from that request whether it started. Asynchronous requests return as soon as they are accepted, which keeps that window short.

```python
import os

import requests

API = "https://api.ideogram.ai"
HEADERS = {"Api-Key": os.environ["IDEOGRAM_API_KEY"]}


def submit(job: dict, store) -> str:
  existing = store.get_generation_id(job["id"])
  if existing:
    response = requests.get(f"{API}/v2/generations/{existing}", headers=HEADERS, timeout=30)
    response.raise_for_status()  # a 429 here means poll later, not resubmit
    if response.json()["status"] != "failed":
      return existing  # already running or done: don't pay twice
  response = requests.post(
    f"{API}/v2/image/generate/ideogram-4-5",
    headers=HEADERS,
    json={"prompt": job["prompt"], "async": True},
    timeout=30,
  )
  response.raise_for_status()
  generation_id = response.json()["generation_id"]
  store.save_generation_id(job["id"], generation_id)  # record before waiting
  return generation_id
```

## Idempotent webhook handlers

Webhook deliveries can repeat. Make your handler process each `generation_id` once and return `2xx` for repeats; see [Webhooks](/v2/ideogram-api/webhooks#retries-idempotency-and-polling). That makes your handler idempotent. It doesn't make request submission idempotent.