API reference

Get generation download

Return a signed download URL for a generation output. Review Diffio API behavior, response fields, setup details, and production workflows.

Return a signed download URL for restored audio or video.

POST/v1/get_generation_downloadPermissions: read

Endpoint

HTTP request

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

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 the project id, generation id, and optional download type.

Body fields

Field	Type	Required	Description
`generationId`	string	Yes	Generation identifier returned by a generation request.
`apiProjectId`	string	Yes	Project identifier for the generation.
`downloadType`	string	No	audio, video, or transcript. Defaults to video for video projects, otherwise audio.

cURL

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

Response

Returns a signed download URL and file metadata.

Response fields

Field	Type	Required	Description
`generationId`	string	Yes	Generation identifier for the request.
`apiProjectId`	string	Yes	Project identifier for the generation.
`downloadType`	string	Yes	audio, video, or transcript based on the request and project type.
`downloadUrl`	string	Yes	Signed URL for downloading the restored file.
`fileName`	string	Yes	File name for the restored asset.
`storagePath`	string	Yes	Storage path for the restored file.
`bucket`	string	Yes	Storage bucket that holds the restored file.
`mimeType`	string	Yes	MIME type of the restored file.

Successful response

{  "generationId": "gen-123",  "apiProjectId": "proj-123",  "downloadType": "audio",  "downloadUrl": "https://storage.googleapis.com/...",  "fileName": "diffio_ai_upload.wav",  "storagePath": "users/user-123/projects/proj-123/generations/gen-123/restored.mp3",  "bucket": "diffio_api",  "mimeType": "audio/mpeg"}

Return codes

200Success, treated as complete.: Download URL returned.
204Success, treated as empty response.: CORS preflight when method is OPTIONS.
400Bad request, treated as client error.: Invalid JSON body, generationId and apiProjectId must be strings, downloadType must be a string, downloadType must be audio, video, or transcript, video downloads are only available for video projects.
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, not permitted to download generations, or does not own the project or generation.
404Not found, treated as missing resource.: Generation not found, restored audio path is not available, restored audio file not found, restored video path is not available, or transcript file not found.
405Client error, treated as fix required.: Method is not POST.
409Conflict, treated as not ready yet.: Generation is not ready yet because processing is not complete or the generation is not marked complete, restored video is not ready yet because the restored job has not succeeded or the blob does not exist.

Notes

downloadType defaults to video for video projects, otherwise audio.
downloadUrl expires after about two hours, request a new one if it expires.
Audio downloads require the generation to be complete and the restored audio file to exist.
Video downloads require a video project, the generation to be complete, and the restored video job to be complete.
Transcript downloads require the generation to be complete and a word_timestamps.json transcript artifact to exist.
API keys must have read permission and downloadGenerations must be true when present.