API reference

Get generation progress

Fetch progress and job stages for a generation. Review Diffio API behavior, response fields, setup details, and production workflows.

Fetch progress and stage details for a generation.

POST/v1/get_generation_progressPermissions: read

Endpoint

HTTP request

https://api.diffio.ai/v1/get_generation_progress

Use POST with a JSON body.

Permissions

read

API keys must be active.

Authentication

Send the API key on every request using one of the supported headers.

Authorization: Bearer <apiKey>
X-Api-Key: <apiKey>
Xi-Api-Key: <apiKey>

Request

Provide a generation id and optionally the project id.

Body fields

Field	Type	Required	Description
`generationId`	string	Yes	Generation identifier returned by a generation request.
`apiProjectId`	string	No	Optional project id to speed up the lookup.

cURL

curl -X POST "https://api.diffio.ai/v1/get_generation_progress" \  -H "Authorization: Bearer $DIFFIO_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "generationId": "gen-123",    "apiProjectId": "proj-123"  }'

Response

Returns overall media status, job stages, and independent transcript availability.

Response fields

Field	Type	Required	Description
`generationId`	string	Yes	Generation identifier for the request.
`apiProjectId`	string	Yes	Project identifier for the generation.
`status`	string	Yes	Overall generation status. complete means the restored media and usage settlement are complete.
`hasVideo`	boolean	Yes	True when the project includes video.
`stage`	string	No	Current processing stage: pending, preparing, transcribing, queued, starting, downloading, decoding, restoring, finalizing, uploading, complete, or failed.
`stageProgress`	object	No	Progress within the current stage while the restore runs: overallPercent, stagePercent, bytesDone and bytesTotal (downloading, uploading), availableThroughSeconds and durationSeconds (restoring).
`queue`	object	No	Present while the generation waits for a processor: position (jobs ahead), connectedWorkers, idleWorkers, busyWorkers, waitReason (all_busy, no_workers, next_in_line), and a readable message.
`preProcessing`	object	No	Stage object for preprocessing.
`inference`	object	No	Stage object for inference.
`restoredVideo`	object	No	Stage object for video restoration when present.
`transcription`	object	No	Independent transcript availability. Older responses may omit this object.
`transcription.status`	string	No	pending, available, or unavailable. Required within transcription when that object is present.
`error`	string	No	Error summary when a stage fails.
`errorDetails`	string	No	Detailed error information when available.

Successful response

{  "generationId": "gen-123",  "apiProjectId": "proj-123",  "status": "processing",  "hasVideo": true,  "stage": "restoring",  "stageProgress": { "overallPercent": 45, "stagePercent": 48, "availableThroughSeconds": 86.4, "durationSeconds": 180 },  "transcription": { "status": "pending" },  "preProcessing": {    "jobId": "job-pre",    "jobState": "SUCCEEDED",    "status": "complete",    "progress": 100,    "statusMessage": null,    "error": null,    "errorDetails": null  },  "inference": {    "jobId": "job-restoration",    "jobState": "RUNNING",    "status": "running",    "progress": 45,    "statusMessage": "Processing audio",    "error": null,    "errorDetails": null  },  "restoredVideo": {    "jobId": "job-restored",    "jobState": "PENDING",    "status": "pending",    "progress": 0,    "statusMessage": "Queued",    "error": null,    "errorDetails": null  }}

Stage object

{  "jobId": "job-123",  "jobState": "RUNNING",  "status": "running",  "progress": 30,  "statusMessage": "Processing",  "error": null,  "errorDetails": null}

Stage object fields

Stage objects share the same fields across preProcessing, inference, and restoredVideo.

Field	Type	Required	Description
`jobId`	string	No	Job identifier when available.
`jobState`	string	No	Cloud job state, for example RUNNING or SUCCEEDED.
`status`	string	Yes	Stage status, for example pending, running, complete, or failed.
`progress`	number	Yes	Progress percentage from 0 to 100.
`statusMessage`	string	No	Optional status message for the current stage.
`error`	string	No	Error summary when the stage fails.
`errorDetails`	string	No	Detailed error information when available.

Return codes

200Success, treated as complete.: Progress returned.
204Success, treated as empty response.: CORS preflight when method is OPTIONS.
400Bad request, treated as client error.: Invalid JSON body, generationId must be provided as a string, apiProjectId must be a string when provided.
401Unauthorized, treated as auth error.: Missing API key, or invalid API key.
403Forbidden, treated as permission error.: API key is not active, missing read permission, or does not own the project or generation.
404Not found, treated as missing resource.: Generation not found.
405Client error, treated as fix required.: Method is not POST.

Notes

generationId is required and apiProjectId is optional.
Overall status values are pending, processing, complete, failed.
Audio projects have preProcessing and inference stage objects; video projects also have restoredVideo.
Overall completion requires validated required media artifacts and durable usage settlement. Keep polling the overall status even when all stage statuses are complete or stage progress is 100%.
Diffio 4.5 transcribes the recording before restoration starts, so a complete generation always has its transcript.
Do not infer transcript availability from an absent transcription object in older responses. Request the transcript download and inspect any structured error.
When a required stage fails, the top level status is failed and error fields are populated.
preProcessing reports complete once the upload has been probed (mediaReady is true and audioDurationSeconds is known), even if the job document is missing.
When a stage is missing, it reports pending with progress set to 0.