> 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.

# Poll a generation

GET https://api.ideogram.ai/v2/generations/{generation_id}

Retrieves the current status of an asynchronous generation, and its
results once complete. Use the `generation_id` returned by any `/v2`
endpoint that runs asynchronously: every video and tool endpoint, and
any image endpoint called with `async` or a `webhook_url`.

While the generation is `pending` or has `failed`, the response
contains only `generation_id`, `status`, and `created` (plus
`failure_reason` once failed). Once `status` is `completed`, the
response includes `response_type` and `data`. Each `data` item carries
an `object_type` that identifies its shape, so image and video results
can be told apart. `usage_cost_usd_micros` reports the amount billed
when the request uses variable usage-based pricing.

Polling is rate limited per organization; a 429 response carries a
`Retry-After` header with the number of seconds to wait.

Reference: https://developer.ideogram.ai/api-reference/generations/get-generation

## Authentication

- `Api-Key` header (required) — API key for access control. Use in the header with the name \"Api-Key\"

## Request

### Path parameters

- `generation_id` (string, required) — URL-safe base64 ID of the generation, as returned when the request was accepted.

## Response

### 200

Generation status retrieved successfully.

- `generation_id` (string, required) — URL-safe base64 ID of the generation.
- `status` (enum, required) — Current status of the generation. `pending`: still in progress; the response contains only `generation_id`, `status`, and `created`. `completed`: finished successfully; the response includes `response_type` and `data`, and may include `usage_cost_usd_micros` when the request uses variable usage-based pricing. `failed`: generation did not succeed; the response contains only `generation_id`, `status`, and `created`.
  - Allowed values: `pending`, `completed`, `failed`
- `created` (datetime, required) — The time the generation was created.
- `response_type` (enum, optional) — Present when `status` is `completed`; always "url" for this shape.
  - Allowed values: `url`
- `usage_cost_usd_micros` (long, optional) — The total variable usage-based cost charged for the completed request, in millionths of a US dollar. Present only when `status` is `completed` and the request uses variable usage-based pricing; omitted otherwise.
- `failure_reason` (string, optional) — A short machine-readable reason the generation failed, for example `content_policy_violation`. Present only when `status` is `failed`.
- `data` (list of GenerationResponse_data_inner, optional) — A list of generated images or videos. Present when `status` is `completed`. Video entries carry an `object_type` of `video.generation`; layerized designs carry `layerized_image`; entries without an `object_type` are images.

## Errors

### 400 Bad Request Error

The generation ID is not a valid URL-safe base64 ID.

- `any`

### 401 Unauthorized Error

Not authorized.

- `any`

### 404 Not Found Error

Generation not found.

- `any`

### 429 Too Many Requests Error

Too many requests.

- `any`

## Types

### GenerationResponse_data_inner

- `object_type`: `image.without-prompt-or-seed` (ImageObjectWithoutPromptOrSeed)
  - `is_image_safe` (boolean, required) — Whether this image passes safety checks. If false, the url field is empty.
  - `resolution` (string, required) — The exact dimensions of the reframed image, formatted as "\{width}x\{height}".
  - `url` (string, optional, nullable) — The direct link to the reframed image.
- `object_type`: `svg.generation` (SvgGenerationObject)
  - `asset_id` (string, required) — URL-safe base64 SVG asset ID.
  - `height` (integer, required) — Height of the output SVG canvas in pixels.
  - `mime_type` (enum, required)
    - Allowed values: `image/svg+xml`
  - `url` (string, required) — Signed download URL for the original SVG.
  - `width` (integer, required) — Width of the output SVG canvas in pixels.
- `object_type`: `image.generation` (ImageGenerationObject)
  - `is_image_safe` (boolean, required) — Whether this image passes safety checks. If false, the url field will be empty.
  - `prompt` (string, required) — The prompt used for the generation. This may be different from the original prompt.
  - `resolution` (string, required) — The resolution of the generated image, formatted as "\{width}x\{height}".
  - `seed` (integer, required) — Random seed. Set for reproducible generation.
  - `url` (string, optional, nullable) — The direct link to the image generated.
- `object_type`: `video.generation` (VideoObject)
  - `aspect_ratio` (string, required) — The actual aspect ratio of the produced video, formatted as "\{width}:\{height}".
  - `duration` (integer, required) — The actual measured length of the produced video in seconds.
  - `prompt` (string, required) — The prompt used for the generation.
  - `resolution` (string, required) — The resolution tier of the generated video.
  - `asset_id` (string, optional) — The generated video's asset ID. Use it with asset_type RESPONSE in video_asset_identifier for a follow-up video edit. This is distinct from the generation ID used for polling.
  - `url` (string, optional, nullable) — The direct link to the generated video.
- `object_type`: `layerized_image` (LayerizedImageObject)
  - `is_image_safe` (boolean, required) — Whether the image passed safety checks. If false, the image links are empty.
  - `resolution` (string, required) — The resolution of the design, formatted as "WIDTHxHEIGHT".
  - `seed` (integer, required) — Random seed. Set for reproducible generation.
  - `text_blocks` (list of DetectedTextBlock, required) — Flat list of detected text regions in the design.
  - `base_image_url` (string, optional, nullable) — The direct link to the base image with all detected text removed. Empty when the image did not pass safety checks.
  - `url` (string, optional, nullable) — The direct link to the design image with its text intact. Empty when the image did not pass safety checks.
- `object_type`: `layerized_design.generation` (TextLayerizerResultObject)
  - `is_image_safe` (boolean, required) — Whether the image passed safety checks. If false, the links are empty.
  - `resolution` (string, required) — The resolution of the design, formatted as "WIDTHxHEIGHT".
  - `seed` (integer, required) — Random seed. Set for reproducible generation.
  - `text_blocks` (list of LayerizedTextBlock, required) — Flat list of detected text regions in the design.
  - `base_image_url` (string, optional, nullable) — Signed link to the base image with all detected text removed. Empty when the image did not pass safety checks.
  - `html_url` (string, optional, nullable) — Signed link to a self-contained HTML page displaying the editable design, including curved text, gradients, outlines, and shadows. The renderer, images, and fonts are embedded in the page, so it keeps working offline once downloaded; the link itself expires after 24 hours. Uploaded `font_candidate_files` are embedded as supplied, so redistributing the page is subject to those fonts' licenses. Empty when the image did not pass safety checks or the page could not be built. The page exposes one editing API for every text layer, whether it is drawn as HTML or on a canvas. Each layer is addressed by its `text_blocks[].layer_id`. Scripts in the page can call `window.layerize` (`ready`, `getTextLayers()`, `setText(id, text)`, `update(id, patch)`, `toJSON()`, `toPNG()`); a parent page that embeds it in an iframe sends `postMessage` requests such as `{"type": "layerize:set-text", "id": "text-0", "text": "Hello"}` and receives `layerize:ready`, `layerize:updated`, and `layerize:error` replies. The page is served sandboxed with an opaque origin, so it cannot read cookies or storage of the site that embeds it.
  - `url` (string, optional, nullable) — Signed link to the design image with its text intact. Empty when the image did not pass safety checks.

### DetectedTextBlock

A single detected text region with its position, content, font information, and styling.

- `x` (integer, required) — X coordinate in pixels from the top-left corner.
- `y` (integer, required) — Y coordinate in pixels from the top-left corner.
- `width` (integer, required) — Width of the text region in pixels.
- `height` (integer, required) — Height of the text region in pixels.
- `text` (string, required) — The detected text content. Line breaks are represented as \n.
- `alignment` (enum, required) — Detected text alignment.
  - Allowed values: `left`, `center`, `right`
- `formatting` (list of enum, required) — Detected text formatting effects.
  - Allowed values: `bold`, `italic`, `underline`, `strikethrough`, `all_caps`, `small_caps`, `superscript`, `subscript`
- `angle` (float, optional, default: 0) — Rotation angle in degrees (clockwise). Defaults to 0.
- `font_name` (string, optional, nullable) — Best-matching font name from the font library.
- `font_alternatives` (list of string, optional, nullable) — Alternative font matches, ranked by similarity.
- `font_size` (integer, optional, nullable) — Detected font size in points.
- `line_height` (float, optional, nullable) — Line height multiplier (e.g., 1.2).
- `color` (string, optional, nullable) — Detected text color in hex format.
- `role` (enum, optional, nullable) — Inferred typographic role of this text block.
  - Allowed values: `heading`, `subheading`, `body`, `caption`

### LayerizedTextBlock

A single detected text region with its position, content, font information, and styling.

- `x` (integer, required) — X coordinate in pixels from the top-left corner.
- `y` (integer, required) — Y coordinate in pixels from the top-left corner.
- `width` (integer, required) — Width of the text region in pixels.
- `height` (integer, required) — Height of the text region in pixels.
- `text` (string, required) — The detected text content. Line breaks are represented as \n.
- `alignment` (enum, required) — Detected text alignment.
  - Allowed values: `left`, `center`, `right`
- `formatting` (list of enum, required) — Detected text formatting effects.
  - Allowed values: `bold`, `italic`, `underline`, `strikethrough`, `all_caps`, `small_caps`, `superscript`, `subscript`
- `layer_id` (string, required) — Identifier of this block's layer in the page at `html_url`; pass it to the page's editing API.
- `angle` (float, optional, default: 0) — Rotation angle in degrees (clockwise). Defaults to 0.
- `font_name` (string, optional, nullable) — Best-matching font name from the font library.
- `font_alternatives` (list of string, optional, nullable) — Alternative font matches, ranked by similarity.
- `font_size` (integer, optional, nullable) — Detected font size in points.
- `line_height` (float, optional, nullable) — Line height multiplier (e.g., 1.2).
- `color` (string, optional, nullable) — Detected text color in hex format.
- `role` (enum, optional, nullable) — Inferred typographic role of this text block.
  - Allowed values: `heading`, `subheading`, `body`, `caption`
- `spans` (list of TextColorSpan, optional, nullable) — The block's colour runs in reading order. Present, with at least one run, whenever `color` is set; concatenating the runs' `text` reproduces the block's `text`. `color` reports the dominant colour.

### TextColorSpan

One run of characters within a text block that shares a single colour. A block whose letters are individually coloured returns one span per letter; a block in a single colour returns one span covering all of it. Concatenating `text` across a block's spans in order reproduces the block's full text.

- `text` (string, required) — The characters in this run.
- `color` (string, required) — Hex colour for this run.

## Examples

**Response**

```json
{
  "generation_id": "bzue-VZtSlSMAneIbfCo2A",
  "status": "completed",
  "created": "2024-01-15T09:30:00Z",
  "response_type": "url",
  "data": [
    {
      "is_image_safe": true,
      "prompt": "prompt",
      "resolution": "2048x2048",
      "seed": 12345,
      "url": "https://ideogram.ai/api/images/ephemeral/xtdZiqPwRxqY1Y7NExFmzB.png?exp=1743867804&sig=e13e12677633f646d8531a153d20e2d3698dca9ee7661ee5ba4f3b64e7ec3f89"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.ideogram.ai/v2/generations/generation_id"

headers = {"Api-Key": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.ideogram.ai/v2/generations/generation_id';
const options = {method: 'GET', headers: {'Api-Key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ideogram.ai/v2/generations/generation_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Api-Key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.ideogram.ai/v2/generations/generation_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Api-Key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.ideogram.ai/v2/generations/generation_id")
  .header("Api-Key", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.ideogram.ai/v2/generations/generation_id', [
  'headers' => [
    'Api-Key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.ideogram.ai/v2/generations/generation_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Api-Key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Api-Key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.ideogram.ai/v2/generations/generation_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```