generate

Poll a generation

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.

get/v1/generations/{generation_id}

Path parameters

generation_idstring required

URL-safe base64 ID of the generation returned by the async generation endpoint.

Response

Generation status retrieved successfully.

generation_idstring required

URL-safe base64 ID of the generation.

status'pending' | 'completed' | 'failed' 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.

createdstring date-time required

The time the generation was created.

response_type'url'

Present when status is completed; always "url" for this shape.

usage_cost_usd_microsinteger

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_reasonstring

A short machine-readable reason the generation failed, for example content_policy_violation. Present only when status is failed.

Example response

{
  "generation_id": "bzue-VZtSlSMAneIbfCo2A",
  "status": "completed",
  "created": "2000-01-23T04:56:07+00:00",
  "response_type": "url",
  "data": [
    {
      "prompt": "prompt",
      "resolution": "2048x2048",
      "seed": 12345,
      "is_image_safe": true,
      "url": "https://ideogram.ai/api/images/ephemeral/xtdZiqPwRxqY1Y7NExFmzB.png?exp=1743867804&sig=e13e12677633f646d8531a153d20e2d3698dca9ee7661ee5ba4f3b64e7ec3f89"
    }
  ]
}

Changes

Changed in 6 of the 34 revisions of this API.817

Sep 19, 2026c891acf371ed1See the full diff
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
Sep 5, 2026c0e3105ea65111See the full diff
- ▲
  added to the / response property oneOf list for the response status
  response-property-one-of-added
- ○
  added layerized_image discriminator mapping keys to the / response property for the response status
  response-property-discriminator-mapping-added
Aug 19, 202673707bc35f341See the full diff
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
Aug 13, 2026e7f5f98d7fdb1See the full diff
- ○
  added the optional property to the response with the status
  response-optional-property-added
Aug 11, 2026b560c0ad061811See the full diff
- ▲
  added to the / response property oneOf list for the response status
  response-property-one-of-added
- ○
  added image.without-prompt-or-seed discriminator mapping keys to the / response property for the response status
  response-property-discriminator-mapping-added
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 26, 20267e5e0fb30776612See the full diff
- ▲
  added to the / response property oneOf list for the response status
  response-property-one-of-added
- ▲
  the / response's property type changed from object to no type for status
  response-property-type-changed
- ▲
  removed the required property // from the response with the status
  response-required-property-removed
- ▲
  removed the required property // from the response with the status
  response-required-property-removed
- ▲
  removed the required property // from the response with the status
  response-required-property-removed
- ▲
  removed the required property // from the response with the status
  response-required-property-removed
- ●
  removed the optional property // from the response with the status
  response-optional-property-removed
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added discriminator to / response property for the response status
  response-property-discriminator-added

Full history