> 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/v1/generations/{generation_id}

Retrieves the current status of an asynchronous generation, and its results once complete. Use the `generation_id` returned by the async generation endpoint. While the generation is `pending` or has `failed`, the response contains only `generation_id`, `status`, and `created`. Once `status` is `completed`, the response includes `response_type` and `data`, and may include `usage_cost_usd_micros` when the request uses variable usage-based pricing.

Reference: https://developer.ideogram.ai/v1/api-reference/generate-images/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 returned by the async generation endpoint.

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

Invalid request ID provided.

- `any`

### 401 Unauthorized Error

Not authorized.

- `any`

### 404 Not Found Error

Request 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`: `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.
  - `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.

### 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`

## 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/v1/generations/generation_id"

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

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

print(response.json())
```

```javascript
const url = 'https://api.ideogram.ai/v1/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/v1/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/v1/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/v1/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/v1/generations/generation_id', [
  'headers' => [
    'Api-Key' => '<apiKey>',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.ideogram.ai/v1/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/v1/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()
```