Skip to main content
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>",
  "keepBackgroundMusic": true,
  "voiceIsolatorOption": "<string>",
  "keepOriginalVoice": true,
  "originalVoiceVolume": 123,
  "subtitles": true,
  "subtitlesSource": "<string>",
  "translationTimeSkips": [
    {
      "translationTimeSkips[].startTime": 123,
      "translationTimeSkips[].endTime": 123,
      "translationTimeSkips[].duration": 123
    }
  ],
  "lipsyncPro": true,
  "voiceCloningSettings": {
    "stability": 123,
    "similarity": 123,
    "speakerBoost": 123
  }
}
'
{
  "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.

​
Concurrency Limit

You can run up to 10 translations at the same time per account. If 5 translations are already in progress, new requests return CONCURRENT_TRANSLATION_LIMIT_REACHED (HTTP 429).

​
Request

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

​
Headers

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

​
Body Parameters

​
file
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/aacMaximum file size: 20 GB
​
targetLanguage
string
required
The language to translate the content into. Must be lowercase.Allowed values: american english, arabic, brazilian portuguese, british english, bulgarian, canadian french, chinese, croatian, czech, danish, dutch, finnish, french, german, greek, hindi, hungarian, indonesian, italian, japanese, korean, malay, mandarin, norwegian, polish, portuguese, romanian, russian, slovak, spanish, swedish, tagalog, tamil, turkish, ukrainian, vietnamese
​
originalLanguage
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
​
projectName
string
A custom name for the project. Useful for identifying projects in your dashboard.Default: The project ID will be used if not provided.
​
keepBackgroundMusic
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
​
voiceIsolatorOption
string
Voice isolation mode when keepBackgroundMusic is enabled. Controls the quality and characteristics of voice separation.
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
​
keepOriginalVoice
boolean
Whether to keep the original background voice (vocal track) underneath the dub.When enabled, the original voice is mixed in the background at a reduced level. Use originalVoiceVolume to control the target level.Default: false
​
originalVoiceVolume
number
The target level for the original background voice bed when keepOriginalVoice is enabled (in dB).Range: 10 - 70 (higher = louder original voice)Default: 30
​
subtitles
boolean
Whether to generate subtitles for the translated video.When enabled, adds clean Netflix-style black and white subtitles. Use subtitlesSource to choose original (source language) or translated (target language) text. Subtitles are automatically synced for optimal readability.Note: Burned-in subtitles require FFmpeg with the subtitles filter (libass). If unavailable, the API falls back to embedding a subtitle track instead of hard-burned styling.Default: false
​
subtitlesSource
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.
​
translationTimeSkips
array
Optional list of time ranges (in seconds) that should not be translated. The original audio (voices + background) is kept for these ranges.Rules:
  • Ranges must be within the media duration and cannot overlap.
  • Ranges cannot include any existing transcription segments.
  • Requires keepBackgroundMusic=true and keepOriginalVoice=false.
Form-data: Send as a JSON string (e.g., -F 'translationTimeSkips=[{\"startTime\":12.5,\"endTime\":18.0,\"duration\":5.5}]').
​
lipsyncPro
boolean
Trigger lip-sync processing after translation completes.
  • false = Standard lip-sync (4 minutes of credits per 1 minute of video)
  • true = Professional lip-sync (9 minutes of credits per 1 minute of video)
    Max duration: 30 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").
​
voiceCloningSettings
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).Default values (balanced):
{
  "stability": 0.6,
  "similarity": 0.85,
  "speakerBoost": 0.6
}
Recommended for avoiding accent reproduction:
{
  "stability": 0.8,
  "similarity": 0.2,
  "speakerBoost": 0.0
}

​
Response

​
success
boolean
required
Always true for successful requests
​
message
string
required
A human-readable message describing the result
​
projectId
string
required
The unique identifier for the created translation project. Use this ID to check status.
​
estimatedDuration
number
required
The detected duration of the uploaded file in seconds

​
Examples

originalVoiceVolume expects a numeric dB level (10-70). Higher values keep more of the original background voice. subtitlesSource accepts translated or original to control which text is used for subtitles.
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 "keepBackgroundMusic=true" \
  -F "voiceIsolatorOption=studio" \
  -F "keepOriginalVoice=true" \
  -F "originalVoiceVolume=40" \
  -F "subtitles=true" \
  -F "subtitlesSource=translated" \
  -F "lipsyncPro=false"

​
Response Example

{
  "success": true,
  "message": "Translation started successfully",
  "projectId": "abc123-def456-ghi789",
  "estimatedDuration": 125.5
}

​
Errors

StatusCodeDescription
400FILE_REQUIREDNo file was uploaded with the request
400INVALID_FILE_TYPEThe uploaded file type is not supported
400DURATION_DETECTION_FAILEDCould not detect the duration of the uploaded file
400INVALID_BOOLEAN_VALUEA boolean parameter has an invalid value (use “true” or “false”)
400INVALID_JSON_FORMATThe voiceCloningSettings JSON is malformed
401INVALID_API_KEYThe provided API key is invalid
403SUBSCRIPTION_REQUIREDAPI access requires a paid subscription
403INSUFFICIENT_CREDITSNot enough credits to process this file
429RATE_LIMIT_EXCEEDEDToo many requests (limit: 10 requests per minute)
429CONCURRENT_TRANSLATION_LIMIT_REACHEDToo many translations in progress (limit: 10 concurrent translations)