Skip to main content
POST
https://api.voicecheap.ai
/
v1
/
translate
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>",
  "subtitles": 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.

​
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
​
subtitles
boolean
Whether to generate subtitles for the translated video.When enabled, adds clean Netflix-style black and white subtitles in the target language. Subtitles are automatically synced to the translated speech for optimal readability.Default: 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.60,
  "similarity": 0.85,
  "speakerBoost": 0.60
}
Recommended for avoiding accent reproduction:
{
  "stability": 0.80,
  "similarity": 0.20,
  "speakerBoost": 0.00
}

​
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

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 "subtitles=true"

​
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: 5 requests per minute)