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
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.
- 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 aLink: rel="successor-version"header and anoticenaming the replacement. See Model lifecycle and deprecations. - Authenticate with the
Api-Keyheader, read from an environment variable on the server. See Authentication and API keys. - 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. - Download results straight away. Result URLs expire after 24 hours. See Responses and metadata.
- Expect asynchronous jobs. Video, tool and some image endpoints return a
generation_id. PollGET /v2/generations/{generation_id}untilstatusiscompletedorfailed, or use a webhook. - 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_idinstead. See Idempotency and safe retries. - Quote before running at volume. Add
dry_run=trueto get a request’s price without running it. See Price quotes. - 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.
- Handle safety results. A
422means the prompt failed the safety check and nothing ran. An image withis_image_safe: falsehas an emptyurl. See Errors and billing.
Point an agent at the docs
A prompt like this one gives an agent what it needs: