Skip to navigation

Responses and Metadata

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

{
"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:

{
"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} until status is completed or failed:

FieldWhen it’s presentMeaning
generation_idAlwaysThe generation’s ID
statusAlwayspending, completed or failed
createdAlwaysWhen the generation was created
response_typecompletedAlways url
datacompletedThe results, each with an object_type
usage_cost_usd_microscompleted, when the request uses variable usage-based pricingThe amount charged, in millionths of a US dollar
failure_reasonfailedA 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).

object_typeFields
image.generationurl, prompt, resolution, seed, is_image_safe
image.without-prompt-or-seedurl, resolution, is_image_safe
svg.generationasset_id, url, mime_type (image/svg+xml), width, height
video.generationasset_id, url, prompt, resolution, aspect_ratio, duration

Layerize results have their own types; see the Layerize reference.

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

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

StoreWhy
generation_idMatch webhook deliveries to your request, and poll the generation again
The downloaded fileResult links expire after 24 hours
prompt and seedRecord how the result was made
resolution, or width and heightKnow the file’s size without opening it
is_image_safeKnow why an image has no url
asset_id, where presentIdentify the result in later requests
usage_cost_usd_micros, where presentReconcile with GET /v2/account/usage
failure_reason, for failed generationsDecide 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.