Start Translation

curl --request POST \
  --url https://api.voicecheap.ai/v1/translate \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "targetLanguage": "<string>",
  "originalLanguage": "<string>",
  "projectName": "<string>",
  "webhookUrl": "<string>",
  "numberOfSpeakers": "<string>",
  "brandVocabulary": "<string>",
  "removeFillerWords": true,
  "sourceSrt": "<string>",
  "translatedSrt": "<string>",
  "keepBackgroundMusic": true,
  "keepOriginalVoice": true,
  "originalVoiceVolume": 123,
  "voiceIsolatorOption": "<string>",
  "subtitles": true,
  "subtitlesSource": "<string>",
  "lipSyncMode": "<string>",
  "activeSpeakerDetectionEnabled": true,
  "lipsyncPro": true,
  "voiceMode": "<string>",
  "voiceId": "<string>",
  "voiceCloningSettings": {
    "stability": 123,
    "similarity": 123
  },
  "translationTimeSkips": "<string>"
}
'

import requests

url = "https://api.voicecheap.ai/v1/translate"

payload = {
    "targetLanguage": "<string>",
    "originalLanguage": "<string>",
    "projectName": "<string>",
    "webhookUrl": "<string>",
    "numberOfSpeakers": "<string>",
    "brandVocabulary": "<string>",
    "removeFillerWords": True,
    "sourceSrt": "<string>",
    "translatedSrt": "<string>",
    "keepBackgroundMusic": True,
    "keepOriginalVoice": True,
    "originalVoiceVolume": 123,
    "voiceIsolatorOption": "<string>",
    "subtitles": True,
    "subtitlesSource": "<string>",
    "lipSyncMode": "<string>",
    "activeSpeakerDetectionEnabled": True,
    "lipsyncPro": True,
    "voiceMode": "<string>",
    "voiceId": "<string>",
    "voiceCloningSettings": {
        "stability": 123,
        "similarity": 123
    },
    "translationTimeSkips": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    targetLanguage: '<string>',
    originalLanguage: '<string>',
    projectName: '<string>',
    webhookUrl: '<string>',
    numberOfSpeakers: '<string>',
    brandVocabulary: '<string>',
    removeFillerWords: true,
    sourceSrt: '<string>',
    translatedSrt: '<string>',
    keepBackgroundMusic: true,
    keepOriginalVoice: true,
    originalVoiceVolume: 123,
    voiceIsolatorOption: '<string>',
    subtitles: true,
    subtitlesSource: '<string>',
    lipSyncMode: '<string>',
    activeSpeakerDetectionEnabled: true,
    lipsyncPro: true,
    voiceMode: '<string>',
    voiceId: '<string>',
    voiceCloningSettings: {stability: 123, similarity: 123},
    translationTimeSkips: '<string>'
  })
};

fetch('https://api.voicecheap.ai/v1/translate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.voicecheap.ai/v1/translate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'targetLanguage' => '<string>',
    'originalLanguage' => '<string>',
    'projectName' => '<string>',
    'webhookUrl' => '<string>',
    'numberOfSpeakers' => '<string>',
    'brandVocabulary' => '<string>',
    'removeFillerWords' => true,
    'sourceSrt' => '<string>',
    'translatedSrt' => '<string>',
    'keepBackgroundMusic' => true,
    'keepOriginalVoice' => true,
    'originalVoiceVolume' => 123,
    'voiceIsolatorOption' => '<string>',
    'subtitles' => true,
    'subtitlesSource' => '<string>',
    'lipSyncMode' => '<string>',
    'activeSpeakerDetectionEnabled' => true,
    'lipsyncPro' => true,
    'voiceMode' => '<string>',
    'voiceId' => '<string>',
    'voiceCloningSettings' => [
        'stability' => 123,
        'similarity' => 123
    ],
    'translationTimeSkips' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.voicecheap.ai/v1/translate"

	payload := strings.NewReader("{\n  \"targetLanguage\": \"<string>\",\n  \"originalLanguage\": \"<string>\",\n  \"projectName\": \"<string>\",\n  \"webhookUrl\": \"<string>\",\n  \"numberOfSpeakers\": \"<string>\",\n  \"brandVocabulary\": \"<string>\",\n  \"removeFillerWords\": true,\n  \"sourceSrt\": \"<string>\",\n  \"translatedSrt\": \"<string>\",\n  \"keepBackgroundMusic\": true,\n  \"keepOriginalVoice\": true,\n  \"originalVoiceVolume\": 123,\n  \"voiceIsolatorOption\": \"<string>\",\n  \"subtitles\": true,\n  \"subtitlesSource\": \"<string>\",\n  \"lipSyncMode\": \"<string>\",\n  \"activeSpeakerDetectionEnabled\": true,\n  \"lipsyncPro\": true,\n  \"voiceMode\": \"<string>\",\n  \"voiceId\": \"<string>\",\n  \"voiceCloningSettings\": {\n    \"stability\": 123,\n    \"similarity\": 123\n  },\n  \"translationTimeSkips\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.voicecheap.ai/v1/translate")
  .header("x-api-key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"targetLanguage\": \"<string>\",\n  \"originalLanguage\": \"<string>\",\n  \"projectName\": \"<string>\",\n  \"webhookUrl\": \"<string>\",\n  \"numberOfSpeakers\": \"<string>\",\n  \"brandVocabulary\": \"<string>\",\n  \"removeFillerWords\": true,\n  \"sourceSrt\": \"<string>\",\n  \"translatedSrt\": \"<string>\",\n  \"keepBackgroundMusic\": true,\n  \"keepOriginalVoice\": true,\n  \"originalVoiceVolume\": 123,\n  \"voiceIsolatorOption\": \"<string>\",\n  \"subtitles\": true,\n  \"subtitlesSource\": \"<string>\",\n  \"lipSyncMode\": \"<string>\",\n  \"activeSpeakerDetectionEnabled\": true,\n  \"lipsyncPro\": true,\n  \"voiceMode\": \"<string>\",\n  \"voiceId\": \"<string>\",\n  \"voiceCloningSettings\": {\n    \"stability\": 123,\n    \"similarity\": 123\n  },\n  \"translationTimeSkips\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.voicecheap.ai/v1/translate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"targetLanguage\": \"<string>\",\n  \"originalLanguage\": \"<string>\",\n  \"projectName\": \"<string>\",\n  \"webhookUrl\": \"<string>\",\n  \"numberOfSpeakers\": \"<string>\",\n  \"brandVocabulary\": \"<string>\",\n  \"removeFillerWords\": true,\n  \"sourceSrt\": \"<string>\",\n  \"translatedSrt\": \"<string>\",\n  \"keepBackgroundMusic\": true,\n  \"keepOriginalVoice\": true,\n  \"originalVoiceVolume\": 123,\n  \"voiceIsolatorOption\": \"<string>\",\n  \"subtitles\": true,\n  \"subtitlesSource\": \"<string>\",\n  \"lipSyncMode\": \"<string>\",\n  \"activeSpeakerDetectionEnabled\": true,\n  \"lipsyncPro\": true,\n  \"voiceMode\": \"<string>\",\n  \"voiceId\": \"<string>\",\n  \"voiceCloningSettings\": {\n    \"stability\": 123,\n    \"similarity\": 123\n  },\n  \"translationTimeSkips\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "projectId": "<string>",
  "estimatedDuration": 123
}

Start Translation

curl --request POST \
  --url https://api.voicecheap.ai/v1/translate \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "targetLanguage": "<string>",
  "originalLanguage": "<string>",
  "projectName": "<string>",
  "webhookUrl": "<string>",
  "numberOfSpeakers": "<string>",
  "brandVocabulary": "<string>",
  "removeFillerWords": true,
  "sourceSrt": "<string>",
  "translatedSrt": "<string>",
  "keepBackgroundMusic": true,
  "keepOriginalVoice": true,
  "originalVoiceVolume": 123,
  "voiceIsolatorOption": "<string>",
  "subtitles": true,
  "subtitlesSource": "<string>",
  "lipSyncMode": "<string>",
  "activeSpeakerDetectionEnabled": true,
  "lipsyncPro": true,
  "voiceMode": "<string>",
  "voiceId": "<string>",
  "voiceCloningSettings": {
    "stability": 123,
    "similarity": 123
  },
  "translationTimeSkips": "<string>"
}
'

import requests

url = "https://api.voicecheap.ai/v1/translate"

payload = {
    "targetLanguage": "<string>",
    "originalLanguage": "<string>",
    "projectName": "<string>",
    "webhookUrl": "<string>",
    "numberOfSpeakers": "<string>",
    "brandVocabulary": "<string>",
    "removeFillerWords": True,
    "sourceSrt": "<string>",
    "translatedSrt": "<string>",
    "keepBackgroundMusic": True,
    "keepOriginalVoice": True,
    "originalVoiceVolume": 123,
    "voiceIsolatorOption": "<string>",
    "subtitles": True,
    "subtitlesSource": "<string>",
    "lipSyncMode": "<string>",
    "activeSpeakerDetectionEnabled": True,
    "lipsyncPro": True,
    "voiceMode": "<string>",
    "voiceId": "<string>",
    "voiceCloningSettings": {
        "stability": 123,
        "similarity": 123
    },
    "translationTimeSkips": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    targetLanguage: '<string>',
    originalLanguage: '<string>',
    projectName: '<string>',
    webhookUrl: '<string>',
    numberOfSpeakers: '<string>',
    brandVocabulary: '<string>',
    removeFillerWords: true,
    sourceSrt: '<string>',
    translatedSrt: '<string>',
    keepBackgroundMusic: true,
    keepOriginalVoice: true,
    originalVoiceVolume: 123,
    voiceIsolatorOption: '<string>',
    subtitles: true,
    subtitlesSource: '<string>',
    lipSyncMode: '<string>',
    activeSpeakerDetectionEnabled: true,
    lipsyncPro: true,
    voiceMode: '<string>',
    voiceId: '<string>',
    voiceCloningSettings: {stability: 123, similarity: 123},
    translationTimeSkips: '<string>'
  })
};

fetch('https://api.voicecheap.ai/v1/translate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.voicecheap.ai/v1/translate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'targetLanguage' => '<string>',
    'originalLanguage' => '<string>',
    'projectName' => '<string>',
    'webhookUrl' => '<string>',
    'numberOfSpeakers' => '<string>',
    'brandVocabulary' => '<string>',
    'removeFillerWords' => true,
    'sourceSrt' => '<string>',
    'translatedSrt' => '<string>',
    'keepBackgroundMusic' => true,
    'keepOriginalVoice' => true,
    'originalVoiceVolume' => 123,
    'voiceIsolatorOption' => '<string>',
    'subtitles' => true,
    'subtitlesSource' => '<string>',
    'lipSyncMode' => '<string>',
    'activeSpeakerDetectionEnabled' => true,
    'lipsyncPro' => true,
    'voiceMode' => '<string>',
    'voiceId' => '<string>',
    'voiceCloningSettings' => [
        'stability' => 123,
        'similarity' => 123
    ],
    'translationTimeSkips' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.voicecheap.ai/v1/translate"

	payload := strings.NewReader("{\n  \"targetLanguage\": \"<string>\",\n  \"originalLanguage\": \"<string>\",\n  \"projectName\": \"<string>\",\n  \"webhookUrl\": \"<string>\",\n  \"numberOfSpeakers\": \"<string>\",\n  \"brandVocabulary\": \"<string>\",\n  \"removeFillerWords\": true,\n  \"sourceSrt\": \"<string>\",\n  \"translatedSrt\": \"<string>\",\n  \"keepBackgroundMusic\": true,\n  \"keepOriginalVoice\": true,\n  \"originalVoiceVolume\": 123,\n  \"voiceIsolatorOption\": \"<string>\",\n  \"subtitles\": true,\n  \"subtitlesSource\": \"<string>\",\n  \"lipSyncMode\": \"<string>\",\n  \"activeSpeakerDetectionEnabled\": true,\n  \"lipsyncPro\": true,\n  \"voiceMode\": \"<string>\",\n  \"voiceId\": \"<string>\",\n  \"voiceCloningSettings\": {\n    \"stability\": 123,\n    \"similarity\": 123\n  },\n  \"translationTimeSkips\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.voicecheap.ai/v1/translate")
  .header("x-api-key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"targetLanguage\": \"<string>\",\n  \"originalLanguage\": \"<string>\",\n  \"projectName\": \"<string>\",\n  \"webhookUrl\": \"<string>\",\n  \"numberOfSpeakers\": \"<string>\",\n  \"brandVocabulary\": \"<string>\",\n  \"removeFillerWords\": true,\n  \"sourceSrt\": \"<string>\",\n  \"translatedSrt\": \"<string>\",\n  \"keepBackgroundMusic\": true,\n  \"keepOriginalVoice\": true,\n  \"originalVoiceVolume\": 123,\n  \"voiceIsolatorOption\": \"<string>\",\n  \"subtitles\": true,\n  \"subtitlesSource\": \"<string>\",\n  \"lipSyncMode\": \"<string>\",\n  \"activeSpeakerDetectionEnabled\": true,\n  \"lipsyncPro\": true,\n  \"voiceMode\": \"<string>\",\n  \"voiceId\": \"<string>\",\n  \"voiceCloningSettings\": {\n    \"stability\": 123,\n    \"similarity\": 123\n  },\n  \"translationTimeSkips\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.voicecheap.ai/v1/translate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"targetLanguage\": \"<string>\",\n  \"originalLanguage\": \"<string>\",\n  \"projectName\": \"<string>\",\n  \"webhookUrl\": \"<string>\",\n  \"numberOfSpeakers\": \"<string>\",\n  \"brandVocabulary\": \"<string>\",\n  \"removeFillerWords\": true,\n  \"sourceSrt\": \"<string>\",\n  \"translatedSrt\": \"<string>\",\n  \"keepBackgroundMusic\": true,\n  \"keepOriginalVoice\": true,\n  \"originalVoiceVolume\": 123,\n  \"voiceIsolatorOption\": \"<string>\",\n  \"subtitles\": true,\n  \"subtitlesSource\": \"<string>\",\n  \"lipSyncMode\": \"<string>\",\n  \"activeSpeakerDetectionEnabled\": true,\n  \"lipsyncPro\": true,\n  \"voiceMode\": \"<string>\",\n  \"voiceId\": \"<string>\",\n  \"voiceCloningSettings\": {\n    \"stability\": 123,\n    \"similarity\": 123\n  },\n  \"translationTimeSkips\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "projectId": "<string>",
  "estimatedDuration": 123
}

Start Translation

Create a new translation project by uploading a video or audio file. The translation process runs asynchronously in the background. Use the status endpoint to track progress and retrieve results. Use Get Project Details when you need translated version history or lip-sync history.

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.

Request

This endpoint accepts multipart/form-data with a file upload.

Headers

string

required

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

Body Parameters

file

required

The video or audio file to translate.Supported video formats: video/mp4, video/quicktime, video/x-matroska, video/webm, video/mpegSupported audio formats: audio/mpeg, audio/wav, audio/mp4, audio/x-m4a, audio/flac, audio/ogg, audio/aac, audio/webmMaximum file size by plan: Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB, and Enterprise 60 GB.

string

required

The language to translate the content into. Must be lowercase.Allowed values (70+): afrikaans, albanian, amharic, arabic, armenian, assamese, azerbaijani, basque, belarusian, bengali, bosnian, bulgarian, catalan, croatian, czech, danish, dutch, english, british english, estonian, finnish, french, french canadian, galician, german, greek, gujarati, hebrew, hindi, hungarian, icelandic, indonesian, irish, italian, japanese, kannada, kazakh, khmer, korean, lao, latvian, lithuanian, macedonian, malay, malayalam, mandarin, marathi, mongolian, nepali, norwegian, persian, polish, portuguese, brazilian portuguese, pt_brazil, punjabi, romanian, russian, serbian, slovak, slovenian, spanish, swahili, swedish, tagalog, tamil, telugu, thai, turkish, ukrainian, urdu, vietnamese, welsh, yoruba, zulu

string

The source language of the content using ISO language codes (e.g., en, es, fr, de, ja, zh).

Strongly recommended: Leave this empty for auto-detection.Only provide this parameter if you are 100% certain the language code is correct and in valid ISO format. Incorrect language codes will cause transcription failures. Our auto-detection supports 80+ languages and is highly accurate.

Default: auto-detect

string

A custom name for the project. Useful for identifying projects in your dashboard.Default: The project ID will be used if not provided.

string

An https endpoint that receives the webhook events for this project, overriding the endpoint configured on your account.Default: The account webhook endpoint, when one is configured.

string

auto-detect or an integer from 1 through 32. A known speaker count can improve diarization.Default: auto-detect

string

A JSON string array of request-specific names, brands, acronyms, or specialist terms. These terms are merged with saved account or team vocabulary.

boolean

Remove common filler words from the source transcript before translation.Default: true

string

An existing source-language SRT transcript. originalLanguage must be explicit when this field is supplied.

string

The final target-language SRT, written by you. When supplied, VoiceCheap skips its translation engine and only generates the voices and mixes the output from this text. See Dub-only mode for the alignment rules. Maximum 1,000,000 characters.

boolean

Whether to preserve background audio in the output.When enabled, keeps background music, ambience, laughs, claps, and crowd sounds while removing only the original voice (stem separation). Turn off if your source has no background audio.Default: true

boolean

Keep the original speaker quietly underneath the translated voice.Default: false

number

Original-voice volume from 1 through 70 when keepOriginalVoice is enabled.Default: 30

string

Voice isolation mode when keepBackgroundMusic is enabled. Controls the quality and characteristics of voice separation.

Studio (Recommended)

Our default voice processing, designed for professional audio quality:

Removes echoes and reverberations
Cleans technical imperfections
Produces a clear and crisp voice

Recommended for: Most projects where audio quality is paramount. Ideal for tutorials, educational content, marketing videos, and any content requiring optimal voice clarity.

Realistic

Preserves the natural characteristics of the recording environment:

Maintains a sound closer to the original recording
Preserves environmental characteristics

Recommended for: Content where the authenticity of the environment is important, such as outdoor vlogs, documentaries, or content where the sound ambiance is an integral part of the experience.

This option may create artifacts or unexpected effects in some cases due to the preservation of background elements.

Allowed values: studio, realisticDefault: studio

boolean

Whether to generate subtitles for the translated video.When enabled, adds clean black-and-white subtitles. Use subtitlesSource to choose original (source language) or translated (target language) text. Subtitles are automatically synced for readability.Default: false

string

Choose the subtitle text source when subtitles is enabled.Allowed values: translated, originalDefault: translatedNote: If original is selected but the original transcription is unavailable, subtitles fall back to translated.

string

Trigger lip-sync processing after translation completes.

standard = Lip Sync
pro = Lip Sync Pro
studio = Lip Sync Studio

Premium modes enforce their normal plan, duration, and credit requirements.Default: omit the field to skip lip sync.

boolean

Enable active-speaker detection for the requested lip-sync run.Default: false

boolean

Legacy lip-sync selector retained for backward compatibility.

false = Standard lip-sync (4 minutes of credits per 1 minute of video)
true = Lip Sync Pro (9 minutes of credits per 1 minute of video)

Lip Sync Pro is available starting on the Creator plan.

Max duration: 180 minutes per video.Latency: Lip-sync processing typically adds 2x-4x the original video duration.

Lip-sync completion and failure emails are not sent for API-triggered requests. Use the status endpoint to track progress.

Default: not enabled (omit the field to skip lip-sync)Form-data: Send boolean values as true or false strings (e.g., -F "lipsyncPro=false").

Do not combine lipsyncPro with a conflicting lipSyncMode.

string

Voice strategy: cloning or custom.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.

object

Fine-tune voice cloning parameters for advanced control over the generated voice. Pass as a JSON string when using form-data. All values must be between 0 and 1 (with step of 0.01). A speakerBoost value sent by earlier integrations is still accepted but no longer has any effect.

These settings apply only when voiceMode is cloning.

Show voiceCloningSettings properties

number

default:"0.60"

Voice Stability (0.00 - 1.00)Determines how stable the voice is and the randomness between each generation.

Lower values allow a wider emotional range but may cause odd or rushed speech
Higher values produce more consistent output but may sound monotone

Default: 0.60 (studio) / 0.65 (realistic)

number

default:"0.80"

Voice Similarity (0.00 - 1.00)Controls how closely the AI adheres to the original voice.

Higher values make the cloned voice more similar to the original
If the original audio is noisy and similarity is too high, artifacts or background noise may carry into the generated voice

Default: 0.80 (studio) / 0.75 (realistic)

Default values (balanced):

{
  "stability": 0.6,
  "similarity": 0.8
}

string

A JSON array of source-time ranges that should remain in the original language.

[
  { "startTime": 10.2, "endTime": 12.8 }
]

Time skips require video input and keepBackgroundMusic=true. They cannot be combined with keepOriginalVoice and cannot overlap transcript segments.

Dub-only mode (bring your own translation)

Send translatedSrt when you already have the translation and only need VoiceCheap for voice generation and mixing. In this mode:

No AI translation and no SmartSync rephrasing. Every cue is voiced verbatim. Saved glossary rules and custom translation instructions are not applied either, because they only run on the translation engine.
Timing comes from the source. Each segment keeps the start, end and speaker of the source transcript; the timecodes of your SRT are only used to match cues to segments. Generated speech is stretched or compressed to fit the segment window without rewording it.
Same credits as a translation. The run is billed exactly like a standard translation of the same media.
Voice, background, subtitles and lip-sync options apply unchanged. voiceMode, keepBackgroundMusic, subtitles, lipSyncMode and the other dubbing options behave as documented above.

The response message confirms the mode, and the translated version reports dubbingMode: "dub-only" in Get Project Details.

Alignment rules

Request	Mode	Rule
`translatedSrt` + `sourceSrt`	`index`	Both files must contain the same number of cues; cue n of the translation is voiced on cue n of the source. A count mismatch is rejected before the upload with `TRANSLATED_SRT_CUE_COUNT_MISMATCH`.
`translatedSrt` only	`timestamps`	The media is transcribed first, then each translated cue is matched to the transcript segment starting within 50 ms of the cue start, or with the largest overlap. Several cues on one segment are joined. A cue matching no segment or a segment left without any cue fails the run.

Alignment problems in timestamps mode are known only after transcription and are reported asynchronously. The status endpoint returns HTTP 200 with status: "failed" and an error containing code and message; the project.translation.failed webhook carries the same code and message. TRANSLATED_SRT_UNMATCHED_CUES names unmatched cue numbers in the message, while TRANSLATED_SRT_MISSING_SEGMENTS names segment indexes without a cue. These responses do not include structured details. For a deterministic mapping, send sourceSrt with translatedSrt, or create the project with Create Project, export its transcript, translate it cue by cue, and call Dub Project.

Checking the pacing

Long sentences must be sped up to fit their segment. Export the translated transcript with Export Project Transcript: each translated segment carries finalSpeedFactor, the ratio between the generated speech and the segment window before the final tempo fit. Shorten the cues that end up above roughly 1.3, then run the dub again with the revised SRT.

translatedSrt is also accepted on the JSON endpoint Dub Project, which dubs an existing project that has already been transcribed, without uploading the media again.

Response

boolean

required

Always true for successful requests

string

required

A human-readable message describing the result

string

required

The unique identifier for the created translation project. Use this ID to check status.

number

required

Rough processing estimate in minutes. The current estimate is five minutes of processing per started minute of source media.

Examples

Saved glossary rules and custom translation instructions from the effective account or team are applied automatically.

curl -X POST https://api.voicecheap.ai/v1/translate \
  -H "x-api-key: vc_your-api-key" \
  -F "file=@video.mp4" \
  -F "targetLanguage=spanish" \
  -F "projectName=My Spanish Translation" \
  -F "numberOfSpeakers=2" \
  -F 'brandVocabulary=["VoiceCheap","SmartSync"]' \
  -F "removeFillerWords=true" \
  -F "keepBackgroundMusic=true" \
  -F "keepOriginalVoice=false" \
  -F "voiceIsolatorOption=studio" \
  -F "subtitles=true" \
  -F "subtitlesSource=translated" \
  -F "lipSyncMode=standard" \
  -F "activeSpeakerDetectionEnabled=true"

interface StartTranslationResponse {
  success: boolean;
  message: string;
  projectId: string;
  estimatedDuration: number;
}

interface VoiceCloningSettings {
  stability: number; // 0.00 - 1.00
  similarity: number; // 0.00 - 1.00
}

interface StartTranslationRequest {
  targetLanguage: string;
  originalLanguage?: string;
  projectName?: string;
  numberOfSpeakers?: 'auto-detect' | string;
  brandVocabulary?: string[];
  removeFillerWords?: boolean;
  sourceSrt?: string;
  translatedSrt?: string;
  keepBackgroundMusic?: boolean;
  keepOriginalVoice?: boolean;
  originalVoiceVolume?: number;
  voiceMode?: 'cloning' | 'custom';
  voiceId?: string;
  voiceIsolatorOption?: 'studio' | 'realistic';
  subtitles?: boolean;
  subtitlesSource?: 'translated' | 'original';
  lipSyncMode?: 'standard' | 'pro' | 'studio';
  activeSpeakerDetectionEnabled?: boolean;
  voiceCloningSettings?: VoiceCloningSettings;
  translationTimeSkips?: Array<{ startTime: number; endTime: number }>;
}

async function startTranslation(
  file: File,
  targetLanguage: string,
  options?: {
    originalLanguage?: string;
    projectName?: string;
    numberOfSpeakers?: 'auto-detect' | string;
    brandVocabulary?: string[];
    removeFillerWords?: boolean;
    sourceSrt?: string;
    translatedSrt?: string;
    keepBackgroundMusic?: boolean;
    keepOriginalVoice?: boolean;
    originalVoiceVolume?: number;
    voiceMode?: 'cloning' | 'custom';
    voiceId?: string;
    voiceIsolatorOption?: 'studio' | 'realistic';
    subtitles?: boolean;
    subtitlesSource?: 'translated' | 'original';
    lipSyncMode?: 'standard' | 'pro' | 'studio';
    activeSpeakerDetectionEnabled?: boolean;
    voiceCloningSettings?: VoiceCloningSettings;
    translationTimeSkips?: Array<{ startTime: number; endTime: number }>;
  },
): Promise<StartTranslationResponse> {
  const formData = new FormData();
  formData.append('file', file);
  formData.append('targetLanguage', targetLanguage);

  if (options?.projectName) {
    formData.append('projectName', options.projectName);
  }
  if (options?.originalLanguage) {
    formData.append('originalLanguage', options.originalLanguage);
  }
  if (options?.numberOfSpeakers) {
    formData.append('numberOfSpeakers', options.numberOfSpeakers);
  }
  if (options?.brandVocabulary) {
    formData.append('brandVocabulary', JSON.stringify(options.brandVocabulary));
  }
  if (options?.removeFillerWords !== undefined) {
    formData.append('removeFillerWords', String(options.removeFillerWords));
  }
  if (options?.sourceSrt) {
    formData.append('sourceSrt', options.sourceSrt);
  }
  if (options?.translatedSrt) {
    formData.append('translatedSrt', options.translatedSrt);
  }
  if (options?.keepBackgroundMusic !== undefined) {
    formData.append('keepBackgroundMusic', String(options.keepBackgroundMusic));
  }
  if (options?.keepOriginalVoice !== undefined) {
    formData.append('keepOriginalVoice', String(options.keepOriginalVoice));
  }
  if (options?.originalVoiceVolume !== undefined) {
    formData.append('originalVoiceVolume', String(options.originalVoiceVolume));
  }
  if (options?.voiceMode) {
    formData.append('voiceMode', options.voiceMode);
  }
  if (options?.voiceId) {
    formData.append('voiceId', options.voiceId);
  }
  if (options?.voiceIsolatorOption) {
    formData.append('voiceIsolatorOption', options.voiceIsolatorOption);
  }
  if (options?.subtitles !== undefined) {
    formData.append('subtitles', String(options.subtitles));
  }
  if (options?.subtitlesSource) {
    formData.append('subtitlesSource', options.subtitlesSource);
  }
  if (options?.lipSyncMode) {
    formData.append('lipSyncMode', options.lipSyncMode);
  }
  if (options?.activeSpeakerDetectionEnabled !== undefined) {
    formData.append('activeSpeakerDetectionEnabled', String(options.activeSpeakerDetectionEnabled));
  }
  if (options?.voiceCloningSettings) {
    formData.append('voiceCloningSettings', JSON.stringify(options.voiceCloningSettings));
  }
  if (options?.translationTimeSkips) {
    formData.append('translationTimeSkips', JSON.stringify(options.translationTimeSkips));
  }

  const response = await fetch('https://api.voicecheap.ai/v1/translate', {
    method: 'POST',
    headers: {
      'x-api-key': 'vc_your-api-key',
    },
    body: formData,
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Translation failed');
  }

  return response.json();
}

// Usage example
const file = document.querySelector<HTMLInputElement>('#fileInput')?.files?.[0];
if (file) {
  const result = await startTranslation(file, 'spanish', {
    projectName: 'My Spanish Translation',
    keepBackgroundMusic: true,
    voiceIsolatorOption: 'studio',
    subtitles: true,
    subtitlesSource: 'translated',
    voiceCloningSettings: {
      stability: 0.6,
      similarity: 0.85,
    },
  });
  console.log('Project ID:', result.projectId);
}

const formData = new FormData();
formData.append('file', videoFile);
formData.append('targetLanguage', 'spanish');
formData.append('projectName', 'My Spanish Translation');
formData.append('keepBackgroundMusic', 'true');
formData.append('voiceIsolatorOption', 'studio');
formData.append('subtitles', 'true');
formData.append('subtitlesSource', 'translated');
formData.append(
  'voiceCloningSettings',
  JSON.stringify({
    stability: 0.6,
    similarity: 0.85,
  }),
);

const response = await fetch('https://api.voicecheap.ai/v1/translate', {
  method: 'POST',
  headers: {
    'x-api-key': 'vc_your-api-key',
  },
  body: formData,
});

const data = await response.json();
console.log('Project ID:', data.projectId);

import requests
import json

files = {'file': open('video.mp4', 'rb')}
data = {
    'targetLanguage': 'spanish',
    'projectName': 'My Spanish Translation',
    'keepBackgroundMusic': 'true',
    'voiceIsolatorOption': 'studio',
    'subtitles': 'true',
    'subtitlesSource': 'translated',
    'voiceCloningSettings': json.dumps({
        'stability': 0.60,
        'similarity': 0.85
    })
}
headers = {'x-api-key': 'vc_your-api-key'}

response = requests.post(
    'https://api.voicecheap.ai/v1/translate',
    headers=headers,
    files=files,
    data=data
)

result = response.json()
print(f"Project ID: {result['projectId']}")

<?php
$curl = curl_init();

$voiceCloningSettings = json_encode([
    'stability' => 0.60,
    'similarity' => 0.85
]);

$postFields = [
    'file' => new CURLFile('video.mp4'),
    'targetLanguage' => 'spanish',
    'projectName' => 'My Spanish Translation',
    'keepBackgroundMusic' => 'true',
    'voiceIsolatorOption' => 'studio',
    'subtitles' => 'true',
    'subtitlesSource' => 'translated',
    'voiceCloningSettings' => $voiceCloningSettings
];

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.voicecheap.ai/v1/translate',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $postFields,
    CURLOPT_HTTPHEADER => [
        'x-api-key: vc_your-api-key'
    ]
]);

$response = curl_exec($curl);
$result = json_decode($response, true);
echo "Project ID: " . $result['projectId'];

Response Example

{
  "success": true,
  "message": "Translation started successfully. Use the status endpoint to track progress.",
  "projectId": "abc123-def456-ghi789",
  "estimatedDuration": 15
}

Errors

Status	Code	Description
400	`FILE_REQUIRED`	No file was uploaded with the request
400	`INVALID_FILE_TYPE`	The uploaded file type is not supported
400	`DURATION_DETECTION_FAILED`	Could not detect the duration of the uploaded file
400	`INVALID_MULTIPART_REQUEST`	Multipart form data is malformed or exceeds field limits
400	`INVALID_BOOLEAN_VALUE`	A boolean parameter has an invalid value (use “true” or “false”)
400	`INVALID_JSON_FORMAT`	The voiceCloningSettings JSON is malformed
400	`INVALID_BRAND_VOCABULARY`	A request-specific vocabulary entry is invalid
400	`INVALID_SOURCE_SRT`	The supplied source SRT is malformed
400	`SOURCE_LANGUAGE_REQUIRED_FOR_SRT`	sourceSrt requires an explicit originalLanguage
400	`INVALID_TRANSLATED_SRT`	The supplied translated SRT is malformed
400	`TRANSLATED_SRT_CUE_COUNT_MISMATCH`	translatedSrt and sourceSrt do not contain the same number of cues
400	`VOICE_ID_REQUIRED`	Custom voice mode was selected without a voice ID
400	`VOICE_ID_NOT_ALLOWED_WITH_CLONING`	A voice ID was combined with voice cloning
400	`VOICE_CLONING_SETTINGS_NOT_ALLOWED`	Clone settings were combined with custom voice mode
400	`CONFLICTING_LIPSYNC_OPTIONS`	lipSyncMode conflicts with legacy lipsyncPro
400	`TRANSLATION_TIME_SKIP_CONFLICT`	Time skips conflict with another audio option
400	`TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND`	Time skips require background audio
400	`TRANSLATION_TIME_SKIP_OUT_OF_RANGE`	A time skip extends beyond the media duration
400	`INVALID_TRANSLATION_TIME_SKIPS`	A time skip overlaps a transcription segment
400	`SUBTITLES_NOT_AVAILABLE_FOR_AUDIO`	Burned-in subtitles were requested for audio input
400	`LIPSYNC_NOT_AVAILABLE_FOR_AUDIO`	Lip sync was requested for audio input
400	`TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO`	Time skips were requested for audio input
400	`LIPSYNC_VIDEO_TOO_LONG`	Lip-sync was requested for media longer than the supported duration
413	`FILE_TOO_LARGE`	The uploaded file exceeds the user’s plan limit
401	`MISSING_API_KEY`	API key is required
401	`INVALID_API_KEY_FORMAT`	API key must start with `vc_`
401	`INVALID_API_KEY`	The provided API key is invalid
403	`SUBSCRIPTION_REQUIRED`	API access requires a Starter plan or higher
403	`INSUFFICIENT_CREDITS`	Not enough credits to process this file
403	`CUSTOM_VOICE_ACCESS_DENIED`	The selected voice is neither a catalog voice nor a custom voice saved by the authenticated account.
403	`LIPSYNC_MODE_ACCESS_DENIED`	The premium lip-sync mode is unavailable on the current plan
429	`RATE_LIMIT_EXCEEDED`	Too many requests (limit: 10 requests per minute)
429	`CONCURRENT_TRANSLATION_LIMIT_REACHED`	Account concurrency limit reached; see `details.limit`

Overview

Discovery

Account

Usage and activity

Settings and notifications

Team

Projects

Translation and dubbing

Transcripts and editing

Text to speech

Speech voices

Dubbing voices

Transcription

Subtitles and captions

Images

Thumbnails

Folders

Glossary

Webhooks

Publishing

Request status

OAuth and MCP protocol

Start Translation

Start Translation

Concurrency Limit

Request

Headers

Body Parameters

Dub-only mode (bring your own translation)

Alignment rules

Checking the pacing

Response

Examples

Response Example

Errors

​Start Translation

​Concurrency Limit

​Request

​Headers

​Body Parameters

​Dub-only mode (bring your own translation)

​Alignment rules

​Checking the pacing

​Response

​Examples

​Response Example

​Errors

Start Translation

Concurrency Limit

Request

Headers

Body Parameters

Dub-only mode (bring your own translation)

Alignment rules

Checking the pacing

Response

Examples

Response Example

Errors