canonical: https://jentic.com/apis/api.ideogram.ai/ideogram

# Ideogram.ai API

The Ideogram.ai API exposes the Ideogram 3.0 image generation model, which is known for accurate in-image text rendering and strong typographic control. Agents can generate images from text prompts, produce variants with transparent backgrounds, edit regions of an existing image with mask-based inpainting, remix and reframe compositions, replace backgrounds, upscale outputs, and describe an image back into a caption. The endpoints all return downloadable image URLs along with model metadata such as seed and style preset.

## For AI agents

Generate, edit, and describe images using the Ideogram 3.0 model - strong at in-image text - through a single REST interface.

## Scope

Does not handle video generation, audio synthesis, or model fine-tuning - use for image generation, editing, upscaling, and captioning only.

## Capabilities

- Generate images from text prompts with explicit aspect ratio and style preset controls, including transparent-background variants
- Edit regions of an existing image using a mask plus a text instruction (inpainting)
- Remix an existing image into a new composition while preserving subject identity
- Reframe an image to a different aspect ratio without manual cropping
- Replace the background of an image with a prompt-driven scene
- Upscale generated or uploaded images to higher resolution
- Describe an image back into a natural-language caption for accessibility or RAG indexing

## Use cases

### Marketing Asset Generation with Legible Text

Generate campaign banners, posters, and social cards where the headline copy must render correctly inside the image. Ideogram 3.0 is engineered for accurate text-in-image, so a single POST `/v1/ideogram-v3/generate` call with a prompt that includes the exact copy returns ready-to-use assets. This avoids the multi-pass workflow of generating an image and then compositing text on top.

Example prompt: Call POST `/v1/ideogram-v3/generate` with the prompt 'modern teal banner with the headline Summer Launch in bold sans-serif' and aspect_ratio 16:9, then return the generated image URL.

### E-Commerce Product Imagery

Produce transparent-background hero shots for e-commerce listings, then reframe and replace backgrounds for category pages, ads, and social posts. Generate-transparent returns a PNG with alpha channel; replace-background composites a new scene around an existing subject. This compresses the studio photo + post-production cycle into a single agent run.

Example prompt: Call POST `/v1/ideogram-v3/generate-transparent` with the prompt 'matte black wireless headphones, studio lighting' and return the alpha PNG URL.

### Iterative Creative Editing

Edit and remix existing images to iterate on a creative direction without re-generating from scratch. The /edit endpoint takes a source image plus a binary mask and a text instruction; /remix preserves the subject while reinterpreting the scene; /reframe extends or crops the canvas to a new aspect ratio. Together these support a tight design feedback loop.

Example prompt: Call POST `/v1/ideogram-v3/edit` with the source image, a mask covering the headline area, and the prompt 'change the headline to Autumn Sale' - return the edited image URL.

### AI Agent Visual Content Generation

An AI agent generating a campaign brief or social calendar can use Ideogram via Jentic to produce the supporting visuals in one workflow. Jentic exposes generate, edit, and describe as discoverable tools so the agent picks the right operation by intent. The Ideogram API key stays in your Jentic One instance.

Example prompt: Search for 'generate an image from text', load the POST `/v1/ideogram-v3/generate` schema, and execute it with the prompt and aspect ratio passed by the agent.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/ideogram-v3/generate` | Generate an image from a text prompt |
| POST | `/v1/ideogram-v3/generate-transparent` | Generate an image with transparent background |
| POST | `/v1/ideogram-v3/edit` | Edit an image region with mask-based inpainting |
| POST | `/v1/ideogram-v3/remix` | Remix an existing image into a new composition |
| POST | `/v1/ideogram-v3/reframe` | Reframe an image to a new aspect ratio |
| POST | `/v1/ideogram-v3/replace-background` | Replace the background of an image |
| POST | `/upscale` | Upscale an image to higher resolution |
| POST | `/describe` | Generate a caption describing an image |

## Key resources

- **Generate** — Text-to-image generation, including transparent-background variants
- **Edit** — Mask-based inpainting, remix, reframe, and background replacement
- **Vision** — Image upscaling and image-to-text description

## Why Jentic

- **Setup:** Wiring the Ideogram.ai API by hand means setting up its API key auth and coding your own calls across the v3 generate, edit, remix, and upscale endpoints. Through Jentic you install once, import the Ideogram.ai API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Ideogram image inputs and prompts travel in the request body rather than as ids in the URL path, so limit the agent to the operations it needs, such as generate or describe, and leave editing operations like edit or replace-background out of the allowed set. Every operation you grant is your explicit choice.
- **Credential handling:** Your Ideogram.ai API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'generate an image from a prompt' or 'upscale an image', and Jentic returns the matching Ideogram operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stability AI API** — Stability AI offers Stable Diffusion family models with broader open-source support; Ideogram specialises in in-image text quality
- **Replicate API** — Replicate hosts hundreds of community models behind one API; Ideogram is a dedicated first-party API for the Ideogram 3.0 model
- **OpenAI API** — OpenAI's image endpoints offer DALL-E and gpt-image-1; Ideogram is a single-model API with stronger typographic control

## FAQ

### What authentication does the Ideogram.ai API use?

The Ideogram API uses an API key passed in the Api-Key request header. When called through Jentic, the key is stored encrypted in your Jentic One instance and attached at execution time, so it never enters agent context or logs.

### Can I generate images with legible text using the Ideogram API?

Yes - accurate in-image text is Ideogram's headline capability. POST `/v1/ideogram-v3/generate` accepts a prompt that includes the exact copy you want rendered, and the model is trained to lay it out as legible typography. Quote the desired text in the prompt for best results.

### What are the rate limits for the Ideogram.ai API?

Ideogram applies per-key rate limits that vary by plan and are not enumerated in the OpenAPI spec; the API returns standard 429 responses with a Retry-After header when exceeded. Plan paid traffic accordingly and queue requests if you need to run large batches.

### How do I edit a region of an image through Jentic?

Run pip install jentic, search for 'edit a region of an image with a mask', and Jentic returns the POST `/v1/ideogram-v3/edit` operation. Load its schema, pass the source image URL or upload, the binary mask, and the prompt describing the change, then execute the call to get the edited image URL.

### Is the Ideogram.ai API free?

No. Ideogram offers a free tier with limited credits and paid plans that scale with usage; pricing is published on ideogram.ai. Each generate, edit, remix, and upscale call consumes credits; the /describe endpoint is typically cheaper since it does not run the diffusion model.

### Can the same API caption an image as well as generate one?

Yes. POST /describe accepts an image URL or file and returns a natural-language description, which is useful for indexing or for feeding caption text back into a generation prompt. This pairs well with /upscale when preparing assets for downstream RAG pipelines.

### Can I limit what my agent is allowed to do with the Ideogram.ai API?

Yes. Because Jentic One is self-hosted, you decide which Ideogram operations your agent may call and store the API key in your own instance. You can allow read-only or low-risk operations such as generate, generate-transparent, or describe while leaving edit, remix, reframe, and replace-background out of the permitted set. Since Ideogram passes images and prompts in the request body rather than as path ids, this per-operation allowlist is what controls what the agent can actually do.