API Overview

The Ideogram API brings Ideogram’s image and video models into your product. Every v2 endpoint follows one pattern, POST /v2/{content}/{action}/{model}, so the model you call is always in the URL: for example /v2/image/generate/ideogram-4-5.

Ideogram 4.5: the most precise edit model

Tell Ideogram 4.5 what to change and it leaves everything else alone. With Precise Edit, pixels the edit doesn’t touch are copied exactly from your image, and the result comes back at your image’s own width and height.

Original, then “Change the product’s colour and finish to slate-blue knit”, then two edits later with a gum sole and a pale lilac backdrop. The shoes keep their exact shape and position throughout.

What you can build

Quickstart

Create an API key by following the Setup guide. Then generate an image with Ideogram 4.5 and make a precise edit to it. Image endpoints return results directly; image URLs expire, so download anything you want to keep.

import requests
API = "https://api.ideogram.ai"
HEADERS = {"Api-Key": "<apiKey>"}
# Generate an image with Ideogram 4.5
response = requests.post(
  f"{API}/v2/image/generate/ideogram-4-5",
  headers=HEADERS,
  json={"prompt": "Knit running shoes in neon coral on a warm stone paper sweep, soft window light"},
)
response.raise_for_status()
with open("shoes.png", "wb") as f:
  f.write(requests.get(response.json()["data"][0]["url"]).content)
# Precisely edit it: only the change you describe
with open("shoes.png", "rb") as image:
  response = requests.post(
    f"{API}/v2/image/precise-edit/ideogram-4-5",
    headers=HEADERS,
    data={"prompt": "Change the shoes to slate-blue knit. Keep everything else exactly the same."},
    files={"image": image},
  )
response.raise_for_status()
print(response.json()["data"][0]["url"])

Long-running requests

Video and tool endpoints always run asynchronously, and any image endpoint does too when you set async or supply a webhook_url. They return a generation_id straight away: poll GET /v2/generations/{generation_id} until status is completed or failed, or receive the result at your webhook.

import time
with open("shoes.png", "rb") as image:
  response = requests.post(
    f"{API}/v2/image/precise-edit/ideogram-4-5",
    headers=HEADERS,
    data={"prompt": "Change the backdrop to a soft pale lilac.", "async": "true"},
    files={"image": image},
  )
generation_id = response.json()["generation_id"]
while True:
  generation = requests.get(f"{API}/v2/generations/{generation_id}", headers=HEADERS).json()
  if generation["status"] != "pending":
    break
  time.sleep(2)
print(generation["status"], generation.get("data"))

Moving from v1

The v1 API keeps working, and its reference stays available under v1 in the version switcher. Each v1 endpoint has a v2 equivalent with the model in the path; request fields differ in places (for example, v1’s text_prompt is v2’s prompt), so check each endpoint’s reference.

Enterprise scale

The Ideogram API serves thousands of API customers generating millions of images daily. If you need more than the default rate limit of 10 in-flight requests, contact us at partnership@ideogram.ai and we’ll help fit your needs.