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 the overall status plus stage objects for each job step.

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 status for the generation.
`hasVideo`	boolean	Yes	True when the project includes video.
`preProcessing`	object	No	Stage object for preprocessing.
`inference`	object	No	Stage object for inference.
`restoredVideo`	object	No	Stage object for video restoration when 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,  "preProcessing": {    "jobId": "job-pre",    "jobState": "SUCCEEDED",    "status": "complete",    "progress": 100,    "statusMessage": null,    "error": null,    "errorDetails": null  },  "inference": {    "jobId": "job-cloud-run-gpu",    "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 return preProcessing and inference only.
Video projects include restoredVideo. Overall completion requires validated required artifacts and durable usage settlement. Keep polling the overall status even when all stage statuses are complete or stage progress is 100%.
When a stage fails, the top level status is failed and error fields are populated.
preProcessing reports complete when audioOriginalMp3Ready is true even if the job document is missing.
When a stage is missing, it reports pending with progress set to 0.