> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://developer.ideogram.ai/v2/llms.txt
> - v1: https://developer.ideogram.ai/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.ideogram.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.ideogram.ai/_mcp/server.

> What the Ideogram API returns: generation IDs, result fields, object types for images, SVGs and video, link expiry, and which fields to store.

Every Ideogram API generation has a `generation_id`. A synchronous request returns its results in `data`; an asynchronous request returns the `generation_id` straight away, and you collect the results by polling or through a [webhook](/v2/ideogram-api/webhooks). Result links expire after 24 hours, so download and store anything you want to keep.

## A synchronous response

Most image endpoints run synchronously by default. A request to `POST /v2/image/generate/ideogram-4-5` returns:

```json
{
  "generation_id": "xtdZiqPwRxqY1Y7NExFmzB",
  "generation_kind": "sampling",
  "seed": 12345,
  "data": [
    {
      "url": "https://ideogram.ai/api/images/ephemeral/xtdZiqPwRxqY1Y7NExFmzB.png",
      "prompt": "A ceramic mug on a wooden table, soft window light",
      "resolution": "2048x2048",
      "seed": 12345,
      "is_image_safe": true
    }
  ]
}
```

`seed` is the seed that was used, including when you didn't set one. `generation_kind` says whether the ID belongs to a single model generation (`sampling`) or a multi-step workflow (`workflow`); you poll both the same way. Some endpoints add fields of their own, such as the output `width` and `height` on upscale responses. Each endpoint's reference lists its response.

## An asynchronous response

These endpoints always run asynchronously: video, tools, SVG generation and vectorizing, Replace Background, Remove Objects and Reframe with Nano Banana 2. Other image endpoints do too when you set `async` or supply a `webhook_url`. The request returns the `generation_id` and no `data`:

```json
{
  "generation_id": "xtdZiqPwRxqY1Y7NExFmzB",
  "generation_kind": "sampling",
  "seed": 12345
}
```

The other fields in the acknowledgement depend on the endpoint; a video acknowledgement, for example, has `generation_id` and `created`.

Poll [`GET /v2/generations/{generation_id}`](/v2/api-reference/generations/get-generation) until `status` is `completed` or `failed`:

| Field                   | When it's present                                               | Meaning                                                             |
| ----------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------- |
| `generation_id`         | Always                                                          | The generation's ID                                                 |
| `status`                | Always                                                          | `pending`, `completed` or `failed`                                  |
| `created`               | Always                                                          | When the generation was created                                     |
| `response_type`         | `completed`                                                     | Always `url`                                                        |
| `data`                  | `completed`                                                     | The results, each with an `object_type`                             |
| `usage_cost_usd_micros` | `completed`, when the request uses variable usage-based pricing | The amount charged, in millionths of a US dollar                    |
| `failure_reason`        | `failed`                                                        | A short machine-readable reason, such as `content_policy_violation` |

## Result types

Each item in a polled `data` array has an `object_type`. Read it before reading the other fields. Webhook deliveries use the same image and SVG items; for video, poll when the delivery arrives (see [Webhooks](/v2/ideogram-api/webhooks#what-ideogram-delivers)).

| `object_type`                  | Fields                                                                |
| ------------------------------ | --------------------------------------------------------------------- |
| `image.generation`             | `url`, `prompt`, `resolution`, `seed`, `is_image_safe`                |
| `image.without-prompt-or-seed` | `url`, `resolution`, `is_image_safe`                                  |
| `svg.generation`               | `asset_id`, `url`, `mime_type` (`image/svg+xml`), `width`, `height`   |
| `video.generation`             | `asset_id`, `url`, `prompt`, `resolution`, `aspect_ratio`, `duration` |

Layerize results have their own types; see the [Layerize reference](/v2/api-reference/images/layerize/ideogram-3).

When an image doesn't pass the safety check, its `is_image_safe` is `false` and its `url` is an empty string.

## Links expire after 24 hours

Image and video links in a response last 24 hours. Each poll of `GET /v2/generations/{generation_id}` returns new links, so you can poll again to get a fresh link within that time. Don't store a link as your permanent copy: download the file and keep it in your own storage.

## What to store

| Store                                    | Why                                                                       |
| ---------------------------------------- | ------------------------------------------------------------------------- |
| `generation_id`                          | Match webhook deliveries to your request, and poll the generation again   |
| The downloaded file                      | Result links expire after 24 hours                                        |
| `prompt` and `seed`                      | Record how the result was made                                            |
| `resolution`, or `width` and `height`    | Know the file's size without opening it                                   |
| `is_image_safe`                          | Know why an image has no `url`                                            |
| `asset_id`, where present                | Identify the result in later requests                                     |
| `usage_cost_usd_micros`, where present   | Reconcile with [`GET /v2/account/usage`](/v2/api-reference/account/usage) |
| `failure_reason`, for failed generations | Decide whether to change the request before trying again                  |

## Use an existing image as an input

Some endpoints accept an image you already have in Ideogram, an upload or a generated result, through an asset identifier field such as `image_asset_identifier`, in place of a file. Each endpoint's reference says which fields it takes and that you supply one or the other, never both.