Skip to main content
In this guide you’ll translate a pre-recorded audio file by creating an async job, uploading the source file, polling until the job completes, and downloading each result. The workflow produces any combination of plain text transcripts, SRT subtitles, and translated speech audio from a single source file. For live audio streams, see the Real-Time Voice Quickstart.
Closed alpha. This API may change without notice and is only available to select DeepL customers. See alpha and beta features for details. To request access, contact your customer success manager.

​
Prerequisites

  • A DeepL API account with Voice Translate Job API access
  • An audio file in a supported source format
  • curl and a shell, or any HTTP client

​
The four-step workflow

Translating a file is always four steps: create a job, upload the file, poll for completion, and download each result. Each step is described below using the same example: a 15 MB English MP3 (podcast-episode-42.mp3) translated into German plain text and Spanish audio.
1

​
Create a job

Send a POST request to /v1/jobs/voice/translate with the source file metadata and your list of target outputs.
A 201 response returns three fields you’ll need immediately:
Save all three. The upload_url is where you’ll PUT the file in the next step. The signature authorizes that upload. The job_id is how you check status and correlate results.
You have 5 minutes from job creation to complete the upload. If you miss the window, create a new job.
2

​
Upload the source file

PUT your audio file directly to the upload_url from the previous response. Include the signature as a query parameter and set Content-Type to match the content_type you declared when creating the job.
A 200 response with no body confirms the upload succeeded. Processing begins immediately.
The content_length you declare when creating the job must exactly match the size of the file you upload. A mismatch causes the upload to be rejected.
3

​
Poll for status

GET /v1/jobs/voice/translate/{job_id} to check progress. Results for each target are returned in the same order as the targets array in your create request.
While processing is underway, each result has "status": "processing":
When a target finishes, its result entry gains "status": "complete" and a download_url plus a signature for that result:
Poll until every result is in a terminal state (complete, failed, or downloaded). A reasonable polling interval is 10-30 seconds for short files; longer files may take several minutes. Check the updated_at timestamp to detect whether the job has made progress since your last poll.Each target is processed independently. A failure on one target does not affect the others — download whichever results are complete.
4

​
Download results

For each complete result, GET the download_url with the result’s signature as a query parameter:
Repeat for each completed result. Save files with the appropriate extension for the output type (text/plain → .txt, application/x-subrip → .srt, audio types → the container format you requested).
Download results promptly. You have 1 hour from the time the source file is uploaded to download all results. Once all targets are downloaded, the job is deleted and returns 404. For full limits, see the Reference.

​
Handling partial failures

Targets fail independently. Always check each result’s status before downloading. If a target fails, the error.message field describes the problem. You cannot retry a failed target — create a new job for any targets that need to be re-processed.

​
Requesting multiple output types

A single job can produce text, subtitles, and audio from the same source file. Add entries to the targets array:
There is no per-job limit on the number of targets; see the Reference for concurrent job limits.

​
Next steps