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

> Generate your first image with the Ideogram API: create a key, put it in an environment variable, send a request in cURL, Python or TypeScript, and save it.

This quickstart takes you from an API key to a saved image. You need an Ideogram account and API credits; [API Setup](/v2/ideogram-api/api-setup) shows how to add both.

## 1. Create an API key

In the Ideogram app, open your avatar and select **API** (or go to [ideogram.ai/platform](https://ideogram.ai/platform)), then select **Create key**. The full key is shown only once, so copy it before you close the dialog.

## 2. Store the key in an environment variable

Keep the key out of your source code, and call the API from your server so the key never reaches a browser or an app bundle.

```bash
export IDEOGRAM_API_KEY="paste-your-key-here"
```

Every request sends the key in the `Api-Key` header. See [Authentication and API keys](/v2/ideogram-api/authentication) for what a key can do.

## 3. Generate an image

Send a prompt to [Generate with Ideogram 4.5](/v2/api-reference/images/generate/ideogram-4-5). The request waits until the image is ready and returns it in `data`.

#### cURL

```bash
curl -X POST https://api.ideogram.ai/v2/image/generate/ideogram-4-5 \
  -H "Api-Key: $IDEOGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A letterpress poster that reads \"Open Studio\" in a bold serif, warm paper texture"}'
```

#### Python

```python
import os

import requests

response = requests.post(
  "https://api.ideogram.ai/v2/image/generate/ideogram-4-5",
  headers={"Api-Key": os.environ["IDEOGRAM_API_KEY"]},
  json={"prompt": 'A letterpress poster that reads "Open Studio" in a bold serif, warm paper texture'},
  timeout=120,
)
response.raise_for_status()
image = response.json()["data"][0]
print(image["url"])

# Links expire after 24 hours, so save the file now.
with open("poster.png", "wb") as file:
  file.write(requests.get(image["url"], timeout=60).content)
```

#### TypeScript

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

const response = await fetch("https://api.ideogram.ai/v2/image/generate/ideogram-4-5", {
  method: "POST",
  headers: {
    "Api-Key": process.env.IDEOGRAM_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: 'A letterpress poster that reads "Open Studio" in a bold serif, warm paper texture',
  }),
});
if (!response.ok) {
  throw new Error(`Ideogram API error ${response.status}: ${await response.text()}`);
}
const { data } = await response.json();
console.log(data[0].url);

// Links expire after 24 hours, so save the file now.
const image = await fetch(data[0].url);
await writeFile("poster.png", Buffer.from(await image.arrayBuffer()));
```

The response holds one result per image:

```json
{
  "generation_id": "xtdZiqPwRxqY1Y7NExFmzB",
  "data": [
    {
      "url": "https://ideogram.ai/api/images/ephemeral/xtdZiqPwRxqY1Y7NExFmzB.png",
      "prompt": "A letterpress poster that reads \"Open Studio\" in a bold serif, warm paper texture",
      "resolution": "2048x2048",
      "seed": 12345,
      "is_image_safe": true
    }
  ]
}
```

`seed` is the seed the model used. Send it back with the same prompt and settings to get a closely matching image. When `is_image_safe` is `false`, the image didn't pass the safety check and its `url` is empty. [Responses and metadata](/v2/ideogram-api/responses-and-metadata) describes every field.

## 4. Save the result

The `url` in a response stops working after 24 hours. The Python and TypeScript examples above download the file straight away. With cURL, save it yourself:

```bash
curl -o poster.png "<url from the response>"
```

## Check the price first

Without `quality`, Ideogram 4.5 renders at `high` when you send no source images. Add `dry_run=true` to any request to get its price without running it or being charged:

```bash
curl -X POST "https://api.ideogram.ai/v2/image/generate/ideogram-4-5?dry_run=true" \
  -H "Api-Key: $IDEOGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A letterpress poster", "quality": "medium"}'
```

See [Price quotes](/v2/ideogram-api/price-quotes) for the response, and [API pricing](https://ideogram.ai/api-pricing) for every rate.

## If something goes wrong

| Status | What it means                           | What to do                                                              |
| ------ | --------------------------------------- | ----------------------------------------------------------------------- |
| `401`  | The key is missing or wrong             | Check that `IDEOGRAM_API_KEY` is set in the shell that runs the request |
| `402`  | Your balance can't cover the request    | Add credits in **Wallet & Billing** in Settings                         |
| `422`  | The prompt didn't pass the safety check | Change the prompt. You aren't charged                                   |
| `429`  | Too many requests are in progress       | Wait, then retry. See [Rate limits](/v2/ideogram-api/rate-limits)       |

[Errors and billing](/v2/ideogram-api/errors) lists every status and whether it's charged.

## Next steps

#### [Choose a model](/v2/ideogram-api/models)

Compare the image, video and vector models, and the endpoint for each task.

#### [Edit an image](/v2/ideogram-api/masked-edits)

Change one region of an image with Precise Edit and a mask.

#### [Run jobs asynchronously](/v2/ideogram-api/production-integration)

Submit, poll or receive webhooks, and store results in production.

#### [Use the app instead](https://docs.ideogram.ai/quick-start-guide)

Make the same image in the Ideogram app, without code.