Skip to navigation

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.

Edit precisely with Ideogram 4.5

Tell Ideogram 4.5 what to change and the edit targets what you describe. With Precise Edit, the result comes back at your image’s own width and height. Check the areas outside the edit before you use the result.

Targeted edits

Change a color, material or detail by describing it. Add a mask to limit the edit to one area.

Edit again and again

Each turn starts from the last result and changes what you describe. Compare each result with the one before it.

Guided by references

Add up to four reference_images to steer the edit with a product, a material, or a style.

Original, then “Change the product’s color and finish to slate-blue knit”, then two edits later with a gum sole and a pale lilac backdrop. In this example the shoes keep their shape and position across the edits.

original
first edit
third edit

What you can build

Quickstart

Create an API key by following the Setup guide and store it in the IDEOGRAM_API_KEY environment variable. Then generate an image with Ideogram 4.5 and make a precise edit to it. Both requests return their results directly. Image URLs expire after 24 hours, so download anything you want to keep. The Quickstart walks through one request step by step.

import os
import requests
API = "https://api.ideogram.ai"
HEADERS = {"Api-Key": os.environ["IDEOGRAM_API_KEY"]}
# 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, tool and SVG endpoints, Replace Background, Remove Objects and Reframe with Nano Banana 2 always run asynchronously, and other image endpoints do 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. See Responses and metadata for what to store, and Build a reliable production integration for the whole lifecycle. To edit one area of an image, see Edit one region with a mask.

import os
import time
import requests
API = "https://api.ideogram.ai"
HEADERS = {"Api-Key": os.environ["IDEOGRAM_API_KEY"]}
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},
)
response.raise_for_status()
generation_id = response.json()["generation_id"]
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
poll = requests.get(f"{API}/v2/generations/{generation_id}", headers=HEADERS, timeout=30)
if poll.status_code == 429: # polling is rate limited: wait as asked
time.sleep(float(poll.headers.get("Retry-After", "5")))
continue
poll.raise_for_status()
generation = poll.json()
if generation["status"] != "pending":
print(generation["status"], generation.get("data"))
break
time.sleep(2)

Moving from v1

The v1 API keeps working, and its reference stays available under v1 in the version switcher. Most v1 endpoints have a v2 replacement with the model in the path; Model lifecycle and deprecations lists all of them. Request fields differ in places (for example, v1’s text_prompt is v2’s prompt), so check each endpoint’s reference. Custom model training (datasets and training runs) is available only in v1; v2 generates with a model you have already trained. See the v1 training tutorial.

v1 endpointv2 endpoint
POST /v1/ideogram-v4/generatePOST /v2/image/generate/ideogram-4
POST /v1/ideogram-v3/generatePOST /v2/image/generate/ideogram-3
POST /v1/ideogram-v4/remixPOST /v2/image/remix/ideogram-4
POST /v1/ideogram-v3/remixPOST /v2/image/remix/ideogram-3
POST /v1/ideogram-v3/inpaintPOST /v2/image/inpaint/ideogram-3
POST /v1/ideogram-v3/reframePOST /v2/image/reframe/ideogram-3
POST /v1/ideogram-v3/replace-backgroundPOST /v2/image/replace-background/ideogram-3
POST /v1/remove-backgroundPOST /v2/image/remove-background/ideogram-1
POST /v1/ideogram-v4/describePOST /v2/image/describe/ideogram-4
GET /v1/generations/{generation_id}GET /v2/generations/{generation_id}

Higher limits

Your organization can have 10 images and videos in progress at once by default. To raise the limit, contact partnership@ideogram.ai. See Rate limits.