Skip to main content
Dub Project

Dub Project

Generate the voices and mix the output of an existing project from a translated SRT that you provide. VoiceCheap does not translate anything on this endpoint: no translation engine, no SmartSync rephrasing, no glossary. Each cue is voiced verbatim on the matching segment of the project transcript, then mixed with the original background, subtitles and optional lip-sync exactly like a regular translation. Use it when your translation is produced elsewhere (a human translator, your own tooling, an automation flow) and you only need VoiceCheap for voice generation. The run is asynchronous: poll Get Translation Status or listen to the webhooks.

Prerequisites

  • The project must exist and its transcription must be complete: create it with Create Project (transcription only) or Start Translation, and wait for transcriptionStatus: "success".
  • Your SRT must cover the project transcript: every transcript segment needs at least one cue, and every cue must fall on a segment. Export the transcript with Export Project Transcript and translate it cue by cue to keep the timecodes.
  • The request is billed like a translation of the same media, with the same credit check. Lip-sync modes add their usual extra credits.

Concurrency Limit

Project creation, translation, and dubbing all check your account’s active-translation limit (at most 10, possibly lower). Only in-progress translation or dubbing runs occupy slots; transcription-only projects do not. If the limit is reached, the API returns CONCURRENT_TRANSLATION_LIMIT_REACHED (HTTP 429). The applied limit is in details.limit. A second run for the same project and target language is also rejected while one is in progress (TRANSLATION_ALREADY_IN_PROGRESS, HTTP 409).

Request

This endpoint accepts a JSON body (Content-Type: application/json). Boolean and numeric options are sent as JSON values, not as strings.

Headers

string
required
Your VoiceCheap API key. Get one from app.voicecheap.ai/page-api.

Path Parameters

string
required
The project identifier returned by Create Project or Start Translation.

Body Parameters

string
required
The language of translatedSrt, lowercase, from the same list as Start Translation. When the project has no work for this language yet, one is created and the language is added to the project.
string
required
The final target-language SRT content (cue number, timing line, text). Maximum 1,000,000 characters. Cues are matched to the transcript segments by timestamps: a cue starting within 50 ms of a segment start is assigned to that segment, otherwise to the segment it overlaps the most. Several cues on one segment are joined with a space. The timing, speaker and order of every voiced segment always come from the project transcript; your timecodes are only used for matching.
string
An https endpoint that receives the webhook events for this project from now on, overriding the endpoint configured on your account.Default: The endpoint already stored on the project, then the account webhook endpoint.
boolean
Keep the original background audio (music, ambience) under the generated voices.Default: true
boolean
Keep the original speaker quietly underneath the generated voice.Default: false
number
Original-voice volume from 1 through 70 when keepOriginalVoice is enabled.Default: 30
string
Voice strategy: cloning (clone the speakers of the project) or custom (use a catalog voice or your saved custom voice).Default: cloning
string
Required when voiceMode is custom. Use an ID from dubbing_voices_list: a catalog voice or a custom voice saved by the authenticated account. Team billing does not grant access to another member’s saved voices.
string
Voice isolation mode when keepBackgroundMusic is enabled: studio or realistic.Default: studio
boolean
Burn subtitles into the output video. Requires a video project.Default: false
string
Subtitle text when subtitles is enabled: translated (your SRT) or original (the source transcript).Default: translated
string
Run lip-sync once the dub is ready: standard, pro or studio. Plan, duration and credit rules are the same as on Start Translation. Requires a video project.Default: omit the field to skip lip-sync.
boolean
Enable active-speaker detection for the requested lip-sync run.Default: false
object
Voice cloning fine-tuning, as a JSON object with stability and similarity between 0 and 1. Only with voiceMode: "cloning". See Start Translation for guidance on each value.
array
Source-time ranges to leave in the original language, as [{ "startTime": 10.2, "endTime": 12.8 }]. Requires a video project and keepBackgroundMusic: true, cannot be combined with keepOriginalVoice, and cannot overlap transcript segments.

Response

boolean
required
Always true for successful requests.
string
required
A human-readable confirmation.
string
required
The project being dubbed.
string
required
The translation work used for targetLanguage. It matches workId in the status, details and transcript endpoints.
number
required
Rough processing estimate in minutes: five minutes of processing per started minute of source media.
Response

Tracking the run

The project switches to the translation workflow as soon as the dub starts, so Get Translation Status follows the new run: status moves from processing to success (with translatedVideoUrl and translatedAudioUrl) or failed (with error). The project.translation.completed and project.translation.failed webhooks are sent with the same targetLanguage. In Get Project Details, the translated version reports settings.dubbingMode: "dub-only" and settings.smartSync: false. Alignment failures appear after the POST has been accepted. The status endpoint returns status: "failed" with error.code and error.message; the project.translation.failed webhook carries the same code and message. TRANSLATED_SRT_UNMATCHED_CUES names unmatched cue numbers in the message, and TRANSLATED_SRT_MISSING_SEGMENTS names segment indexes without a cue in the message. These asynchronous responses do not include structured details. Fix the SRT and call the endpoint again: the failed version stays in the project history and a new one is created.

Checking the pacing

Export the translated transcript as JSON with Export Project Transcript. Each segment carries finalSpeedFactor, the ratio between the generated speech and the segment window. Shorten the cues above roughly 1.3, then run the dub again with the revised SRT.

Example flow

A typical automation (for example an n8n or Make scenario) chains the endpoints as follows:
  1. POST /v1/projects with the media, targetLanguage and an explicit originalLanguage (transcription only).
  2. Poll GET /v1/translate/{projectId}/status until transcriptionStatus is success, or wait for the project.created webhook.
  3. POST /v1/projects/{projectId}/transcript with { "source": "original", "outputFormat": "srt" } and translate the cues, keeping the numbering and timecodes.
  4. POST /v1/projects/{projectId}/dub with the translated SRT.
  5. Poll the status endpoint until status is success, or wait for project.translation.completed.
  6. Download translatedVideoUrl (or lipSync.videoUrl when lip-sync was requested).
  7. DELETE /v1/translate/{projectId} once the outputs are stored on your side.

Errors

Alignment failures detected while the run executes (TRANSLATED_SRT_UNMATCHED_CUES, TRANSLATED_SRT_MISSING_SEGMENTS) are returned by the status endpoint and the failed webhook, not by this request.