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