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.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://api.diffio.ai/v2/projects/{project_id}/generations/{generation_id}

  • Key scope: generations:read
  • Auth header:Authorization: Bearer <apiKey>
  • Body: None

Overall status

  1. queued
  2. processing
  3. complete
  4. or failed

stage while it runs

  1. pending
  2. preparing
  3. transcribing
  4. queued
  5. starting
  6. downloading
  7. decoding
  8. restoring
  9. finalizing
  10. uploading
  11. complete
  12. or failed

stage_progress in the example response

overall_percent
88%
available_through_seconds
0 of 31.8 s
Poll until status is complete or failed.

Request

Pass project_id and generation_id in the path; takes no request body.

Path parameters

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

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)

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

Response

Returns the generation object.

Success: 200OK.

Response fields

FieldTypePresentDescription
#idstringAlwaysUnique generation identifier (UUID).
#objectstringAlwaysResource type, always "generation".generation
#statusstringAlwaysLifecycle state: queued, processing, complete, or failed.queuedprocessingcompletefailed
#modelstring | nullAlwaysHosted model that ran or is running (such as diffio-4.7-flash or diffio-4.7-pro), or null.
#stagestring | nullAlwaysCurrent worker stage (pending, preparing, transcribing, queued, starting, downloading, decoding, restoring, finalizing, uploading, then complete or failed), or null.
#stage_progressobject | nullAlwaysLive worker progress while status is processing, or null before a worker reports progress and after completion.Fields below
#queueobject | nullAlwaysWorker queue snapshot while the generation waits to start, or null otherwise.Fields below
#errorobject | nullAlwaysFailure details when status is failed (also includes boolean retryable and nullable explanation on the wire), or null otherwise.
#error.codestringAlwaysStable snake_case generation failure code (such as restoration_failed, no_speech_detected, transcription_failed, upload_missing, or generation_failed).
#error.messagestringAlwaysHuman-readable message explaining why the generation failed.
stage_progress 6 fields
FieldTypePresentDescription
#stage_progress.overall_percentnumberSometimesOverall generation completion percentage from 0 to 100, present once reported.
#stage_progress.stage_percentnumberSometimesCompletion percentage of the current stage from 0 to 100, present once reported.
#stage_progress.bytes_donenumberSometimesBytes transferred so far in a downloading or uploading stage.
#stage_progress.bytes_totalnumberSometimesTotal bytes to transfer in the current downloading or uploading stage.
#stage_progress.available_through_secondsnumberSometimesSeconds of restored output already playable via hls_master while processing.
#stage_progress.duration_secondsnumberSometimesRecording length in seconds as reported by the worker.
queue 6 fields
FieldTypePresentDescription
#queue.positioninteger | nullAlwaysNumber of queued jobs ahead of this generation, or null.
#queue.connected_workersinteger | nullAlwaysTotal workers connected to the queue, or null.
#queue.idle_workersinteger | nullAlwaysConnected workers currently idle, or null.
#queue.busy_workersinteger | nullAlwaysConnected workers currently running jobs, or null.
#queue.wait_reasonstring | nullAlwaysWhy the job is waiting (all_busy, no_workers, or next_in_line), or null.
#queue.messagestringAlwaysHuman-readable message explaining why the generation is waiting.
Other response fields34 fields
FieldTypePresentDescription
#project_idstringAlwaysIdentifier of the parent project.
#requested_modelstring | nullAlwaysModel name sent in the request (hosted model, tier alias, or retired model), or null.
#substitutedbooleanAlwaysTrue 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_usdnumber | nullAlwaysList price per hour in USD applied to this generation (for retired models, the lower of the requested and serving models' list prices), or null.
#warningsarrayAlwaysNon-fatal warnings recorded during processing (the generation still runs).Fields below
#labelstring | nullAlwaysCaller-supplied label (up to 120 characters), Transcript edit for an edit, or null when none was set.
#kindstringAlwaysGeneration kind: restore for a full recording restore, or edit for a transcript edit of a finished Pro generation.restoreedit
#source_generation_idstring | nullAlwaysFor kind: "edit", the Pro generation that was edited; null for restore.
Show all 17 fields (9 more)
FieldTypePresentDescription
#editobject | nullAlwaysTranscript edit details and progress when kind is edit, or null for restore.Fields below
#transcript_editablebooleanAlwaysTrue when this result's transcript can be edited via POST .../edits (a finished Pro result with stored edit latents).
#duration_secondsnumber | nullAlwaysDuration of the restored output in seconds once known, or null.
#quality_scorenumber | nullAlwaysEstimated speech quality score of the result from 1 to 5, or null.
#transcription_statusstring | nullAlwaysWord-timed transcript status: preparing, ready, or failed; null when no transcription is reported.preparingreadyfailed
#files_availablearrayAlwaysSorted names of artifacts currently available from GET .../media (such as audio, video, hls_master, transcript, stems_manifest).
#stems_statusstring | nullAlwaysSeparated speech and background track status: preparing, ready, or failed; null when none are reported.preparingreadyfailed
#created_atstring | nullAlwaysISO 8601 UTC timestamp when the generation was created, or null.
#updated_atstring | nullAlwaysISO 8601 UTC timestamp when the generation last changed, or null.
warnings[] 3 fields
FieldTypePresentDescription
#warnings[].codestringAlwaysWarning code; unsupported_language when the transcript contains words in languages the model cannot restore.unsupported_language
#warnings[].languagesarraySometimesISO 639-1 language codes of unsupported words, ordered by word count.
#warnings[].messagestringAlwaysHuman-readable warning message.
edit 14 fields
FieldTypePresentDescription
#edit.edit_countinteger | nullAlwaysNumber of edits (each run of changed, inserted, or removed words between kept words counts once), or null.
#edit.max_windowsinteger | nullAlwaysMaximum number of 30-second windows this edit could restore, or null.
#edit.windowsinteger | nullAlwaysActual number of windows restored (or being restored) by the worker, or null before starting.
#edit.windows_doneinteger | nullAlwaysNumber of restore windows completed so far, or null.
#edit.rangesarrayAlwaysTime ranges on the recording (in seconds) covered by the restored windows.
#edit.ranges[].startnumberSometimesWindow start time in seconds.
#edit.ranges[].endnumberSometimesWindow end time in seconds.
#edit.billable_secondsinteger | nullAlwaysSeconds billed once complete (30 per restored window, 0 when no window was restored), or null until complete.
#edit.cut_secondsnumber | nullAlwaysSeconds trimmed from the recording by tighten, or null.
#edit.request_idstring | nullAlwaysCaller-supplied request_id from the edit request, or null.
#edit.languagestring | nullAlwaysPrimary language code used for the edit, or null.
#edit.tightenobject | nullAlwaysSilence-shortening settings applied by the edit, or null when none were requested.
#edit.tighten.close_removed_gapsbooleanAlwaysWhether silence left by removed words was closed.
#edit.tighten.max_pause_secondsnumber | nullAlwaysMaximum pause duration in seconds after shortening, or null when pauses were left unchanged.

Response 200OK.

Response: key fields
{
  "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-User exceeds 128 characters. invalid_header
  • 403Forbidden: the key lacks permission.Key is inactive or lacks generations:read. permission_denied
  • 404Not found.Project not found, or no generation with generation_id belongs to 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

  • Poll every couple of seconds until status is complete or failed (the SDKs' generations.wait(...) helper does this with a 2-second default interval), or subscribe to generation.completed and generation.failed webhooks.
  • Separated speech and background tracks can finish after status reaches complete; wait for stems_status: "ready" (or the generation.stems_ready webhook) before calling mix or export routes.
  • hls_master appears in files_available while the generation is still processing and can be streamed progressively via Get a playback grant.

Report an issue with this page