> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/api-reference/get-generation-media/.

# Get a playback grant

Mints a 6-hour playback and download grant (`files`) mapping each available artifact of the generation (plus the project's `original` upload) to a signed media URL.

GET `https://api.diffio.ai/v2/projects/{project_id}/generations/{generation_id}/media`

- Key scope: `artifacts:read`
- Auth header: `Authorization: Bearer <apiKey>`
- Body: None

## Request

Pass `project_id` and `generation_id` in the path, and optional `preview_seconds` in the query string.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | string | Yes | Unique identifier of the project. |
| `generation_id` | string | Yes | Unique identifier of the generation within the project. |

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `preview_seconds` | integer | No | Optional playback limit in seconds, from `4` to `3600` (rounded up to whole 4-second segments). Omits full-length download files. |

### Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `Diffio-End-User` | string | No | Optional end-user identifier (up to 128 characters). Scopes the request to that end user's projects; omit to act across the whole account. |

## Example request

**Python**

```python
import os
from diffio import DiffioClient

key = os.environ["DIFFIO_API_KEY"]
client = DiffioClient(api_key=key)

media = client.generations.media(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
    "ce832a32-a1ce-516a-b8bd-75457bd8517f",
)
```

**Node.js**

```javascript
import { DiffioClient } from "diffio"

const client = new DiffioClient({
  apiKey: process.env.DIFFIO_API_KEY,
})

const media =
  await client.generations.media(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
    "ce832a32-a1ce-516a-b8bd-75457bd8517f",
  )
```

**cURL**

```bash
curl "https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/media" \
  -H "Authorization: Bearer $DIFFIO_API_KEY"
```

## Response

Returns `files` (artifact name to signed URL), `base_url`, and `expires_at` (6 hours from issuance).

Success: `200`

### Response fields

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `object` | string | Always | Resource type, always `"generation_media"`. |
| `project_id` | string | Always | Identifier of the parent project. |
| `generation_id` | string | Always | Identifier of the generation. |
| `status` | string | Always | Current lifecycle status of the generation (`queued`, `processing`, `complete`, or `failed`). |
| `files` | object | Always | Map of existing artifact names (`audio`, `video`, `audio_mixed`, `hls_master`, `hls_restored`, `hls_original`, `waveform_restored`, `waveform_original`, `transcript`, `stems_manifest`, `metadata`, `video_hls`, `edited_transcript`, `original`) to signed URLs. |
| `base_url` | string | Always | Common URL prefix of every entry in `files`; relative entries inside HLS playlists and `stems_manifest` resolve against their own URL. |
| `expires_at` | string | Always | ISO 8601 UTC timestamp when every URL in this grant expires (6 hours after creation); call again to mint fresh URLs. |
| `preview_seconds` | integer \| null | Always | Effective preview cap in seconds (rounded up to a multiple of `4`), or `null` when full-length access was granted. |

## Example response (200)

**Successful response**

```json
{
  "object": "generation_media",
  "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
  "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f",
  "status": "complete",
  "base_url": "https://media.diffio.io/m/v1.REDACTED/",
  "expires_at": "2026-11-13T06:33:47Z",
  "preview_seconds": null,
  "files": {
    "audio": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/restored.mp3",
    "audio_mixed": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/mixed.mp3",
    "hls_master": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/master.m3u8",
    "hls_original": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/noisy/index.m3u8",
    "hls_restored": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/clean/index.m3u8",
    "metadata": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/metadata.json",
    "original": "https://media.diffio.io/m/v1.REDACTED/original/interview.mp3",
    "stems_manifest": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/stems/4014a8c299444bbb866971bbb7b657ca/manifest.v2.json",
    "transcript": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/word_timestamps.json",
    "waveform_original": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/visualizations/hls_waveform_noisy.json",
    "waveform_restored": "https://media.diffio.io/m/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/visualizations/hls_waveform_clean.json"
  }
}
```

## Return codes

- `200` Returns signed media URLs valid until `expires_at`.
- `400` `preview_seconds` is outside `4` to `3600`, or `Diffio-End-User` exceeds 128 characters. [`invalid_parameter`](https://diffio.ai/docs/api-reference/errors/#invalid_parameter) [`invalid_header`](https://diffio.ai/docs/api-reference/errors/#invalid_header)
- `403` Key is inactive or lacks `artifacts:read`. [`permission_denied`](https://diffio.ai/docs/api-reference/errors/#permission_denied)
- `404` Project not found, or generation not found on this project. [`project_not_found`](https://diffio.ai/docs/api-reference/errors/#project_not_found) [`generation_not_found`](https://diffio.ai/docs/api-reference/errors/#generation_not_found)
- **`401` `405` Same on every endpoint**

  - `401` Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).
  - `405` HTTP method not supported on this path; check the Allow header (code method_not_allowed).

### Example error response

Errors are JSON: an `error` object with `code`, `message` and `request_id`. An unrecognized key returns `401`:

**Error response**

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "request_id": "dead773b60e148fd9e22d680a22fa701"
  }
}
```

## Notes

- Signed URLs in `files` require no `Authorization` header (safe for browser `<audio>`, `<video>`, and HLS players). Append `?download=<filename>` to any URL in `files` to set `Content-Disposition` for a browser download.
- Works in any generation `status` (unlike transcripts or stems, it never returns `409` `not_ready`), listing whichever files exist so far; `hls_master` grows live as a running generation progresses.
- When `preview_seconds` is set, full-length files (`audio`, `audio_mixed`, `video`, `transcript`, `metadata`, `edited_transcript`) are omitted from `files` and segment reads past the preview return `403`.

## Related pages

- Previous: [Get a generation](https://diffio.ai/docs/api-reference/get-generation/): Check one generation's status, live stage progress, queue position, available files, or failure reason.
- Next: [Estimate a transcript edit](https://diffio.ai/docs/api-reference/estimate-transcript-edit/): Estimate the changed word runs, 30-second windows, and maximum billable seconds of a Pro transcript edit.

- [Models](https://diffio.ai/docs/overview/models/): Choosing between Diffio 4.7 Flash and Pro.
- [API model cards](https://diffio.ai/api-model-cards/): Best uses for each model id.
- [API pricing](https://diffio.ai/api-pricing/): The current rate per hour for each model.
- [Webhooks guide](https://diffio.ai/docs/developers/webhooks/): Get notified when a generation finishes instead of polling.
