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 |
| 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.
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. |
Related pages
