Media responses

Generation endpoints return a consistent response structure. Use this page to understand what you get back, what expires, and what to store on your side.

Response structure

Every completed generation includes these fields:

Field	Type	Description
`id`	string	Unique generation identifier, for example `req-01HXYZABCD1234`
`status`	string	`completed` for images, `pending`, `failed`, or `completed` for videos
`model`	string	The model used for the generation
`data`	array	Generated media items
`usage`	object	Billing information

Sync vs async

Images return HTTP 200 with status: "completed" and the full response body immediately. Videos return HTTP 202 with status: "pending" and only an id when you submit the generation. Poll GET /v2/videos/generations/{id} until the status changes to completed or failed. See Generate videos for the full flow.

The data array

Each item in data represents a generated file. Image items:

Field	Type	Description
`url`	string	Signed download URL
`width`	integer	Image width in pixels
`height`	integer	Image height in pixels
`mime_type`	string	e.g. `image/png`, `image/webp`
`deletes_at`	string	ISO 8601 timestamp when the file expires

Video items include additional fields:

Field	Type	Description
`duration`	number	Video length in seconds
`fps`	number	Frames per second
`has_sound`	boolean	Whether audio is included

Download URLs

The url in each data item is a signed download URL to the generated media.

curl -o output.png "https://api.getimg.ai/v2/downloads/req-01HXYZABCD1234/0?exp=1760000000&sig=1d9c2f..."

Download URLs expire at the deletes_at timestamp.

If your integration needs the file later, download it immediately and store it in your own system. That keeps your delivery flow predictable.

Usage and billing

The usage object contains billing details for the generation.

{
  "total_cost": 0.5,
  "billable_unit": "video_second",
  "unit_price": 0.05,
  "quantity": 10
}

Field	Description
`total_cost`	Total cost for this generation
`billable_unit`	`image` for images, `video_second` for videos
`unit_price`	Cost per unit
`quantity`	Number of units. This is `1` for images and duration in seconds for videos.

Getting started

Generation

Concepts

Response structure

Sync vs async

The data array

Download URLs

Usage and billing

​Response structure

​Sync vs async

​The data array

​Download URLs

​Usage and billing

​Related pages

Response structure

Sync vs async

The data array

Download URLs

Usage and billing

Related pages