> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getimg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Media responses

> Response format for generated media.

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](/guides/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.

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

<Warning>
  Download URLs expire at the `deletes_at` timestamp.
</Warning>

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.

```json theme={null}
{
  "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

* [Generate images](/guides/generate-images)
* [Generate videos](/guides/generate-videos)
* [Billing](/guides/billing)