For AI agents: every API docs page in one plain-text file is at /docs/llms-full.txt, and the documentation index is at /llms.txt. This page is available as Markdown at https://diffio.ai/docs/api-reference/get-generation-media.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

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:/
- 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
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
#preview_seconds | integer | Required: 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 | Required: 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. |
Request
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",
)Response
Returns files (artifact name to signed URL), base_url, and expires_at (6 hours from issuance).
Success: 200OK.
Response fields
| Field | Type | Present | Description |
|---|---|---|---|
#object | string | Always | Resource type, always "generation_media".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).queuedprocessingcompletefailed |
#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. |
Response 200OK.
{
"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
200OK.Returns signed media URLs valid untilexpires_at.400Bad request.preview_secondsis outside4to3600, orDiffio-End-Userexceeds 128 characters.invalid_parameterinvalid_header403Forbidden: the key lacks permission.Key is inactive or lacksartifacts:read.permission_denied404Not found.Project not found, or generation not found on this project.project_not_foundgeneration_not_found401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint401Unauthorized: the API key is missing or invalid. Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).405Client error. 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 401Unauthorized: the API key is missing or invalid.:
{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key.",
"request_id": "dead773b60e148fd9e22d680a22fa701"
}
}Notes
- Signed URLs in
filesrequire noAuthorizationheader (safe for browser<audio>,<video>, and HLS players). Append?download=<filename>to any URL infilesto setContent-Dispositionfor a browser download. - Works in any generation
status(unlike transcripts or stems, it never returns409not_ready), listing whichever files exist so far;hls_mastergrows live as a running generation progresses. - When
preview_secondsis set, full-length files (audio,audio_mixed,video,transcript,metadata,edited_transcript) are omitted fromfilesand segment reads past the preview return403.