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

> Give AI coding agents the Ideogram API docs: llms.txt, Markdown pages, the docs MCP server, and the rules agents most often get wrong in an integration.

Coding agents such as Claude Code, Cursor and Codex write better Ideogram integrations when they read the current docs instead of relying on what they remember. This page lists the machine-readable copies of the docs and the rules to hand an agent before it starts.

## Machine-readable docs

| Resource                      | Address                                                                                                                    | What it holds                                                                                                                                                    |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API docs index                | [`https://developer.ideogram.ai/v2/llms.txt`](https://developer.ideogram.ai/v2/llms.txt)                                   | Every v2 guide and endpoint page with a one-line summary                                                                                                         |
| Any API docs page as Markdown | Add `.md` to the page's URL                                                                                                | The page without navigation, for example [`/v2/ideogram-api/quickstart.md`](https://developer.ideogram.ai/v2/ideogram-api/quickstart.md)                         |
| OpenAPI specification         | [`https://developer.ideogram.ai/openapi/ideogram-api-v2.json`](https://developer.ideogram.ai/openapi/ideogram-api-v2.json) | Every v2 endpoint, field and response schema. `/openapi.json` at the site root is a page that lists the APIs, not a spec                                         |
| Docs MCP server               | `https://developer.ideogram.ai/_mcp/server`                                                                                | Lets an MCP client search these docs. It doesn't generate images                                                                                                 |
| User guide index              | [`https://docs.ideogram.ai/llms.txt`](https://docs.ideogram.ai/llms.txt)                                                   | Every page of the app's user guide. Each page is also available as Markdown, and [`llms-full.txt`](https://docs.ideogram.ai/llms-full.txt) holds the whole guide |

To let an assistant generate and edit images in a conversation, connect it to the [Ideogram MCP server](/v2/ideogram-api/mcp-server) instead. MCP use spends your workspace's credits the same way the Ideogram app does.

## Rules to give an agent

Paste these into your agent's instructions or project rules file. Each one prevents a mistake agents make with this API.

1. **Use v2 endpoints.** The model is in the path: `POST /v2/image/generate/ideogram-4-5`. An older endpoint still works, but its response carries a `Link: rel="successor-version"` header and a `notice` naming the replacement. See [Model lifecycle and deprecations](/v2/ideogram-api/deprecations).
2. **Authenticate with the `Api-Key` header**, read from an environment variable on the server. See [Authentication and API keys](/v2/ideogram-api/authentication).
3. **Send files as `multipart/form-data`.** Endpoints that take images, masks or audio accept uploads only in multipart requests. Requests without files can be JSON where the endpoint allows it.
4. **Download results straight away.** Result URLs expire after 24 hours. See [Responses and metadata](/v2/ideogram-api/responses-and-metadata).
5. **Expect asynchronous jobs.** Video, tool and some image endpoints return a `generation_id`. Poll `GET /v2/generations/{generation_id}` until `status` is `completed` or `failed`, or use a [webhook](/v2/ideogram-api/webhooks).
6. **Don't resend a request that timed out.** The API takes no idempotency key, so every request is a new, billed generation. Poll the `generation_id` instead. See [Idempotency and safe retries](/v2/ideogram-api/idempotency).
7. **Quote before running at volume.** Add `dry_run=true` to get a request's price without running it. See [Price quotes](/v2/ideogram-api/price-quotes).
8. **Check mask colors per endpoint.** Precise Edit and Inpaint edit the black area. Remove Objects and GPT Image edit the white area. See [Edit one region with a mask](/v2/ideogram-api/masked-edits).
9. **Handle safety results.** A `422` means the prompt failed the safety check and nothing ran. An image with `is_image_safe: false` has an empty `url`. See [Errors and billing](/v2/ideogram-api/errors).

## Point an agent at the docs

A prompt like this one gives an agent what it needs:

```text
Build a function that generates a product image with the Ideogram API and saves it to S3.
Read https://developer.ideogram.ai/v2/llms.txt first, then the pages it links for the
endpoint you choose. Follow the rules in https://developer.ideogram.ai/v2/ideogram-api/ai-tools.md.
```