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.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

Get a generation
Returns one generation, including its status, live stage and stage_progress, worker queue details, files_available, stems_status, transcription_status, and error when failed.
GET https:/
- Key scope:
generations:read - Auth header:
Authorization: Bearer <apiKey> - Body: None
Overall status
- queued
- processing
- complete
- or failed
stage while it runs
- pending
- preparing
- transcribing
- queued
- starting
- downloading
- decoding
- restoring
- finalizing
- uploading
- complete
- or failed
stage_progress in the example response
overall_percent- 88%
available_through_seconds- 0 of 31.8 s
status is complete or failed. Request
Pass project_id and generation_id in the path; takes no request body.
Path parameters
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)
generation = client.generations.get(
"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
"ce832a32-a1ce-516a-b8bd-75457bd8517f",
)Response
Returns the generation object.
Success: 200OK.
Response fields
| Field | Type | Present | Description |
|---|---|---|---|
#id | string | Always | Unique generation identifier (UUID). |
#object | string | Always | Resource type, always "generation".generation |
#status | string | Always | Lifecycle state: queued, processing, complete, or failed.queuedprocessingcompletefailed |
#model | string | null | Always | Hosted model that ran or is running (such as diffio-4.7-flash or diffio-4.7-pro), or null. |
#stage | string | null | Always | Current worker stage (pending, preparing, transcribing, queued, starting, downloading, decoding, restoring, finalizing, uploading, then complete or failed), or null. |
#stage_progress | object | null | Always | Live worker progress while status is processing, or null before a worker reports progress and after completion.Fields below |
#queue | object | null | Always | Worker queue snapshot while the generation waits to start, or null otherwise.Fields below |
#error | object | null | Always | Failure details when status is failed (also includes boolean retryable and nullable explanation on the wire), or null otherwise. |
#error. | string | Always | Stable snake_case generation failure code (such as restoration_failed, no_speech_detected, transcription_failed, upload_missing, or generation_failed). |
#error. | string | Always | Human-readable message explaining why the generation failed. |
stage_progress 6 fields
| Field | Type | Present | Description |
|---|---|---|---|
#stage_progress. | number | Sometimes | Overall generation completion percentage from 0 to 100, present once reported. |
#stage_progress. | number | Sometimes | Completion percentage of the current stage from 0 to 100, present once reported. |
#stage_progress. | number | Sometimes | Bytes transferred so far in a downloading or uploading stage. |
#stage_progress. | number | Sometimes | Total bytes to transfer in the current downloading or uploading stage. |
#stage_progress. | number | Sometimes | Seconds of restored output already playable via hls_master while processing. |
#stage_progress. | number | Sometimes | Recording length in seconds as reported by the worker. |
queue 6 fields
| Field | Type | Present | Description |
|---|---|---|---|
#queue. | integer | null | Always | Number of queued jobs ahead of this generation, or null. |
#queue. | integer | null | Always | Total workers connected to the queue, or null. |
#queue. | integer | null | Always | Connected workers currently idle, or null. |
#queue. | integer | null | Always | Connected workers currently running jobs, or null. |
#queue. | string | null | Always | Why the job is waiting (all_busy, no_workers, or next_in_line), or null. |
#queue. | string | Always | Human-readable message explaining why the generation is waiting. |
Other response fields34 fields
| Field | Type | Present | Description |
|---|---|---|---|
#project_id | string | Always | Identifier of the parent project. |
#requested_model | string | null | Always | Model name sent in the request (hosted model, tier alias, or retired model), or null. |
#substituted | boolean | Always | True when requested_model was a retired model name and ran on the current hosted model of the same tier; false for hosted names and aliases. |
#price_per_hour_usd | number | null | Always | List price per hour in USD applied to this generation (for retired models, the lower of the requested and serving models' list prices), or null. |
#warnings | array | Always | Non-fatal warnings recorded during processing (the generation still runs).Fields below |
#label | string | null | Always | Caller-supplied label (up to 120 characters), Transcript edit for an edit, or null when none was set. |
#kind | string | Always | Generation kind: restore for a full recording restore, or edit for a transcript edit of a finished Pro generation.restoreedit |
#source_generation_id | string | null | Always | For kind: "edit", the Pro generation that was edited; null for restore. |
Show all 17 fields (9 more)
| Field | Type | Present | Description |
|---|---|---|---|
#edit | object | null | Always | Transcript edit details and progress when kind is edit, or null for restore.Fields below |
#transcript_editable | boolean | Always | True when this result's transcript can be edited via POST .../edits (a finished Pro result with stored edit latents). |
#duration_seconds | number | null | Always | Duration of the restored output in seconds once known, or null. |
#quality_score | number | null | Always | Estimated speech quality score of the result from 1 to 5, or null. |
#transcription_status | string | null | Always | Word-timed transcript status: preparing, ready, or failed; null when no transcription is reported.preparingreadyfailed |
#files_available | array | Always | Sorted names of artifacts currently available from GET .../media (such as audio, video, hls_master, transcript, stems_manifest). |
#stems_status | string | null | Always | Separated speech and background track status: preparing, ready, or failed; null when none are reported.preparingreadyfailed |
#created_at | string | null | Always | ISO 8601 UTC timestamp when the generation was created, or null. |
#updated_at | string | null | Always | ISO 8601 UTC timestamp when the generation last changed, or null. |
warnings[] 3 fields
| Field | Type | Present | Description |
|---|---|---|---|
#warnings[] | string | Always | Warning code; unsupported_language when the transcript contains words in languages the model cannot restore.unsupported_language |
#warnings[] | array | Sometimes | ISO 639-1 language codes of unsupported words, ordered by word count. |
#warnings[] | string | Always | Human-readable warning message. |
edit 14 fields
| Field | Type | Present | Description |
|---|---|---|---|
#edit. | integer | null | Always | Number of edits (each run of changed, inserted, or removed words between kept words counts once), or null. |
#edit. | integer | null | Always | Maximum number of 30-second windows this edit could restore, or null. |
#edit. | integer | null | Always | Actual number of windows restored (or being restored) by the worker, or null before starting. |
#edit. | integer | null | Always | Number of restore windows completed so far, or null. |
#edit. | array | Always | Time ranges on the recording (in seconds) covered by the restored windows. |
#edit. | number | Sometimes | Window start time in seconds. |
#edit. | number | Sometimes | Window end time in seconds. |
#edit. | integer | null | Always | Seconds billed once complete (30 per restored window, 0 when no window was restored), or null until complete. |
#edit. | number | null | Always | Seconds trimmed from the recording by tighten, or null. |
#edit. | string | null | Always | Caller-supplied request_id from the edit request, or null. |
#edit. | string | null | Always | Primary language code used for the edit, or null. |
#edit. | object | null | Always | Silence-shortening settings applied by the edit, or null when none were requested. |
#edit. | boolean | Always | Whether silence left by removed words was closed. |
#edit. | number | null | Always | Maximum pause duration in seconds after shortening, or null when pauses were left unchanged. |
Response 200OK.
{
"id": "ce832a32-a1ce-516a-b8bd-75457bd8517f",
"object": "generation",
"status": "processing",
"stage": "finalizing",
"stage_progress": {
"overall_percent": 88,
"stage_percent": 0,
"available_through_seconds": 0,
"duration_seconds": 31.8
},
"queue": null,
"error": null,
"model": "diffio-4.7-flash"
}Return codes
200OK.Returns the requested generation.400Bad request.Diffio-End-Userexceeds 128 characters.invalid_header403Forbidden: the key lacks permission.Key is inactive or lacksgenerations:read.permission_denied404Not found.Project not found, or no generation withgeneration_idbelongs to 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
- Poll every couple of seconds until
statusiscompleteorfailed(the SDKs'generations.wait(...)helper does this with a 2-second default interval), or subscribe togeneration.completedandgeneration.failedwebhooks. - Separated speech and background tracks can finish after
statusreachescomplete; wait forstems_status: "ready"(or thegeneration.stems_readywebhook) before calling mix or export routes. hls_masterappears infiles_availablewhile the generation is stillprocessingand can be streamed progressively via Get a playback grant.