Skip to navigation

Authentication and API Keys

Every Ideogram API request authenticates with an API key in the Api-Key header. Ideogram doesn’t offer scoped or restricted keys, and keys don’t expire. Keep the key in an environment variable on your server:

export IDEOGRAM_API_KEY="paste-your-key-here"
curl https://api.ideogram.ai/v2/image/generate/ideogram-4-5 \
-H "Api-Key: $IDEOGRAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "A ceramic mug on a wooden table, soft window light"}'

To create your first key, follow API Setup.

What a key can do

  • Workspace-wide access. A key can call every generation endpoint its workspace can use and spend that workspace’s balance. An endpoint or model your organization can’t use returns 403.
  • Account endpoints need billing access. GET /v2/account/usage, GET /v2/account/invoices and GET /v2/account/api-keys answer only keys created by someone who can see the workspace’s billing. Other keys get 404.
  • Who pays. A request is billed to the workspace the key belongs to. On the Team plan, it uses the credits of the member who created the key. See which balance a key uses in the user guide.
  • Shown once. Settings shows the full key only when you create it. Store it in a secret manager or environment variable, and keep it out of client-side code and public repositories.
  • No expiry. A key works until you revoke it.
  • Revocation is immediate and permanent. Revoke a key from Settings → API in the Ideogram app. Requests with it fail straight away, and it can’t be restored.

Separate environments

Keys in one workspace share its balance and access, so give each environment its own API team when you need separate balances or separate people. Each team has its own keys, credits and billing. Create one with Create an API team in the workspace switcher in Settings; see Teams.

In an API team:

  • Members can create keys, see the team’s key list and use the team’s API, but can’t see Billing.
  • Owners and Admins can also label and revoke keys, and manage billing and members.

Other workspace types, such as the Team plan and Enterprise agreements, handle keys differently; the user guide’s Ideogram API page compares them.

GET /v2/account/api-keys lists the keys on your account.

Rotate a key

  1. Create a new key in API Keys.
  2. Deploy it to every application that uses the old key.
  3. Confirm the applications work with the new key.
  4. Revoke the old key.

Revoking before every application has the new key stops those applications’ requests.