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

> Overview of the Ideogram API v2 — precise image editing with Ideogram 4.5, generation, video, and where to start.

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](/v2/api-reference/images/precise-edit/ideogram-4-5), 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.

#### Targeted edits

Change a colour, material, or detail and keep the rest of the image untouched. Add a `mask` to limit the edit to one area.

#### Consistent across edits

Chain edit after edit with minimal drift: shape, texture, and colour hold steady from one turn to the next.

#### 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 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.*

![](/_fern-img/3ab860bf2397ba02f3539f9f20b1ea5b8f25463195ba4bda1ce80836d0f610ac.webp)

![](/_fern-img/c1881492a1074bc19ae5f5d9ce2fbeb6b3140ef9d3beb304540f1a16551f750b.webp)

![](/_fern-img/cd1cd4f72cbf471cb9a808670ce3692760b0ae24332d15e4899ff371d06cd1a0.webp)

## What you can build

#### [Generate](/v2/api-reference/images/generate/ideogram-4-5)

Create images from a prompt with Ideogram 4.5 and 4.0, known for prompt fidelity and crisp typography, or with GPT Image and Nano Banana.

#### [Remix and inpaint](/v2/api-reference/images/remix/ideogram-4)

Transform an existing image with a prompt, or repaint just the masked region.

#### [Upscale](/v2/api-reference/images/upscale/auto)

Enlarge images with Topaz and Nano Banana Pro, or let Ideogram pick the model.

#### [Backgrounds](/v2/api-reference/images/remove-background/ideogram-1)

Remove a background for a transparent cutout, or replace it with a generated scene.

#### [Video](/v2/api-reference/video/generate/seedance-2-5-text-to-video)

Generate video from text, a first frame, or reference images with Seedance, MiniMax H3, and Kling.

#### [Tools](/v2/api-reference/tools/ad-resizer)

Ready-made workflows for ads and commerce: resize, localize, recolour, and swap materials.

## Quickstart

Create an API key by following the [Setup guide](/v2/ideogram-api/api-setup). 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.

#### Python

```python
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"])
```

#### TypeScript

```typescript
import { readFile, writeFile } from "node:fs/promises";

const API = "https://api.ideogram.ai";
const headers = { "Api-Key": "<apiKey>" };

// Generate an image with Ideogram 4.5
const generated = await fetch(`${API}/v2/image/generate/ideogram-4-5`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    prompt: "Knit running shoes in neon coral on a warm stone paper sweep, soft window light",
  }),
}).then((response) => response.json());
const image = await fetch(generated.data[0].url).then((response) => response.arrayBuffer());
await writeFile("shoes.png", Buffer.from(image));

// Precisely edit it: only the change you describe
const form = new FormData();
form.append("prompt", "Change the shoes to slate-blue knit. Keep everything else exactly the same.");
form.append("image", new Blob([await readFile("shoes.png")]), "shoes.png");
const edited = await fetch(`${API}/v2/image/precise-edit/ideogram-4-5`, {
  method: "POST",
  headers,
  body: form,
}).then((response) => response.json());
console.log(edited.data[0].url);
```

#### cURL

```bash
# Generate an image with Ideogram 4.5
curl -X POST https://api.ideogram.ai/v2/image/generate/ideogram-4-5 \
  -H "Api-Key: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Knit running shoes in neon coral on a warm stone paper sweep, soft window light"}'

# Precisely edit an image: only the change you describe
curl -X POST https://api.ideogram.ai/v2/image/precise-edit/ideogram-4-5 \
  -H "Api-Key: <apiKey>" \
  -F image=@shoes.png \
  -F prompt="Change the shoes to slate-blue knit. Keep everything else exactly the same."
```

### 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}`](/v2/api-reference/generations/get-generation) until `status` is `completed` or `failed`, or receive the result at your [webhook](/v2/ideogram-api/webhooks).

```python
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.

| v1 endpoint                               | v2 endpoint                                    |
| ----------------------------------------- | ---------------------------------------------- |
| `POST /v1/ideogram-v4/generate`           | `POST /v2/image/generate/ideogram-4`           |
| `POST /v1/ideogram-v3/generate`           | `POST /v2/image/generate/ideogram-3`           |
| `POST /v1/ideogram-v4/remix`              | `POST /v2/image/remix/ideogram-4`              |
| `POST /v1/ideogram-v3/remix`              | `POST /v2/image/remix/ideogram-3`              |
| `POST /v1/ideogram-v3/inpaint`            | `POST /v2/image/inpaint/ideogram-3`            |
| `POST /v1/ideogram-v3/reframe`            | `POST /v2/image/reframe/ideogram-3`            |
| `POST /v1/ideogram-v3/replace-background` | `POST /v2/image/replace-background/ideogram-3` |
| `POST /v1/remove-background`              | `POST /v2/image/remove-background/ideogram-1`  |
| `POST /v1/ideogram-v4/describe`           | `POST /v2/image/describe/ideogram-4`           |
| `GET /v1/generations/{generation_id}`     | `GET /v2/generations/{generation_id}`          |

## 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](mailto:partnership@ideogram.ai)* and we'll help fit your needs.