Skip to content

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://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

FieldTypeRequiredDescription
#project_idstringRequired: YesUnique identifier of the project.
#generation_idstringRequired: YesUnique identifier of the generation within the project.

Query parameters

FieldTypeRequiredDescription
#preview_secondsintegerRequired: NoOptional playback limit in seconds, from 4 to 3600 (rounded up to whole 4-second segments). Omits full-length download files.

Headers

FieldTypeRequiredDescription
#Diffio-End-UserstringRequired: NoOptional 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

FieldTypePresentDescription
#objectstringAlwaysResource type, always "generation_media".generation_media
#project_idstringAlwaysIdentifier of the parent project.
#generation_idstringAlwaysIdentifier of the generation.
#statusstringAlwaysCurrent lifecycle status of the generation (queued, processing, complete, or failed).queuedprocessingcompletefailed
#filesobjectAlwaysMap 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_urlstringAlwaysCommon URL prefix of every entry in files; relative entries inside HLS playlists and stems_manifest resolve against their own URL.
#expires_atstringAlwaysISO 8601 UTC timestamp when every URL in this grant expires (6 hours after creation); call again to mint fresh URLs.
#preview_secondsinteger | nullAlwaysEffective preview cap in seconds (rounded up to a multiple of 4), or null when full-length access was granted.

Response 200OK.

Successful response
{
  "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 until expires_at.
  • 400Bad request.preview_seconds is outside 4 to 3600, or Diffio-End-User exceeds 128 characters. invalid_parameterinvalid_header
  • 403Forbidden: the key lacks permission.Key is inactive or lacks artifacts:read. permission_denied
  • 404Not found.Project not found, or generation not found on this project. project_not_foundgeneration_not_found
  • 401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint
    • 401Unauthorized: 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 response
{
  "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.

Report an issue with this page