API reference
Get generation download
Return a download URL for a generation output. Review Diffio API behavior, response fields, setup details, and production workflows.
Return a download URL for restored audio, video, or an available transcript.
POST
/v1/get_generation_downloadEndpoint
HTTP request
https://api.diffio.ai/v1/get_generation_downloadUse 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 download URL, valid for 6 hours, 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 | URL for downloading the restored file, valid for 6 hours. |
fileName | string | Yes | File name for the restored asset. |
storagePath | string | Yes | Storage path for the restored file. |
mimeType | string | Yes | MIME type of the restored file. |
Successful response
{ "generationId": "gen-123", "apiProjectId": "proj-123", "downloadType": "audio", "downloadUrl": "https://media.diffio.io/m/v1.eyJ0eXAiOiJtZWRpYSJ9.signature/generations/gen-123/restored.mp3?download=diffio_ai_upload.mp3", "fileName": "diffio_ai_upload.mp3", "storagePath": "api/users/user-123/projects/proj-123/generations/gen-123/restored.mp3", "mimeType": "audio/mpeg"}Pending transcript (409)
Pending transcript (409)
{ "error": "Transcript is not ready yet.", "code": "TRANSCRIPT_PENDING", "transcription": { "status": "pending" }}Unavailable transcript (404)
Unavailable transcript (404)
{ "error": "Transcript is unavailable.", "code": "TRANSCRIPT_UNAVAILABLE", "transcription": { "status": "unavailable" }}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 or media artifact not found, or transcript unavailable. Transcript unavailability includes code TRANSCRIPT_UNAVAILABLE and transcription.status unavailable.405Client error, treated as fix required.: Method is not POST.409Conflict, treated as not ready yet.: Generation or restored video is not ready, or transcript is pending. A pending transcript includes code TRANSCRIPT_PENDING and transcription.status pending.
Notes
- downloadType defaults to video for video projects, otherwise audio.
- downloadUrl is a signed Diffio media URL that needs no Authorization header. It expires after 6 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 an available word_timestamps.json artifact; otherwise they return TRANSCRIPT_PENDING (409) or TRANSCRIPT_UNAVAILABLE (404).
- Poll generation progress and retry a pending transcript download explicitly. Check the error code as well as the HTTP status to distinguish transcript availability from other 409 or 404 errors.
- API keys must have read permission and downloadGenerations must be true when present.