Skip to navigation

Idempotency and Safe Retries

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}. 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.

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.

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. That makes your handler idempotent. It doesn’t make request submission idempotent.