Skip to navigation

Build with AI Coding Agents

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

ResourceAddressWhat it holds
API docs indexhttps://developer.ideogram.ai/v2/llms.txtEvery v2 guide and endpoint page with a one-line summary
Any API docs page as MarkdownAdd .md to the page’s URLThe page without navigation, for example /v2/ideogram-api/quickstart.md
OpenAPI specificationhttps://developer.ideogram.ai/openapi/ideogram-api-v2.jsonEvery v2 endpoint, field and response schema. /openapi.json at the site root is a page that lists the APIs, not a spec
Docs MCP serverhttps://developer.ideogram.ai/_mcp/serverLets an MCP client search these docs. It doesn’t generate images
User guide indexhttps://docs.ideogram.ai/llms.txtEvery page of the app’s user guide. Each page is also available as Markdown, and 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 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.
  2. Authenticate with the Api-Key header, read from an environment variable on the server. See Authentication and API keys.
  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.
  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.
  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.
  7. Quote before running at volume. Add dry_run=true to get a request’s price without running it. See 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.
  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.

Point an agent at the docs

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

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.