Skip to navigation

Quickstart

This quickstart takes you from an API key to a saved image. You need an Ideogram account and API credits; 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), 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.

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

Every request sends the key in the Api-Key header. See Authentication and API keys for what a key can do.

3. Generate an image

Send a prompt to Generate with Ideogram 4.5. The request waits until the image is ready and returns it in data.

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"}'

The response holds one result per image:

{
"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 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:

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:

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 for the response, and API pricing for every rate.

If something goes wrong

StatusWhat it meansWhat to do
401The key is missing or wrongCheck that IDEOGRAM_API_KEY is set in the shell that runs the request
402Your balance can’t cover the requestAdd credits in Wallet & Billing in Settings
422The prompt didn’t pass the safety checkChange the prompt. You aren’t charged
429Too many requests are in progressWait, then retry. See Rate limits

Errors and billing lists every status and whether it’s charged.

Next steps