> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Start Translation

> Upload a video or audio file and start a new translation project

# 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](https://api-docs.voicecheap.ai/docs/api-reference/translation-status.md) to track progress and retrieve results. Use [Get Project Details](https://api-docs.voicecheap.ai/docs/api-reference/project-details.md) 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

**x-api-key** `string` *required*

Your VoiceCheap API key. Get one from [app.voicecheap.ai/page-api](https://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/mpeg`

**Supported audio formats:** `audio/mpeg`, `audio/wav`, `audio/mp4`, `audio/x-m4a`, `audio/flac`, `audio/ogg`, `audio/aac`, `audio/webm`

**Maximum file size by plan:** Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB, and Enterprise 60 GB.

**targetLanguage** `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`

**originalLanguage** `string`

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

> [!WARNING]
>
> **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.

**webhookUrl** `string`

An https endpoint that receives the [webhook events](https://api-docs.voicecheap.ai/docs/api-reference/webhooks.md) for this project,
overriding the endpoint configured on your account.

**Default:** The account webhook endpoint, when one is configured.

**numberOfSpeakers** `string`

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

**Default:** `auto-detect`

**brandVocabulary** `string`

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

**removeFillerWords** `boolean`

Remove common filler words from the source transcript before translation.

**Default:** `true`

**sourceSrt** `string`

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

**translatedSrt** `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](#dub-only-mode-bring-your-own-translation)
for the alignment rules. Maximum 1,000,000 characters.

**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`

**keepOriginalVoice** `boolean`

Keep the original speaker quietly underneath the translated voice.

**Default:** `false`

**originalVoiceVolume** `number`

Original-voice volume from `1` through `70` when `keepOriginalVoice` is enabled.

**Default:** `30`

**voiceIsolatorOption** `string` *deprecated*

Deprecated. Voice isolation is no longer configurable: every project isolates voices the same way. `studio` and `realistic` are still accepted and have no effect.

**subtitles** `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`

**subtitlesSource** `string`

Choose the subtitle text source when `subtitles` is enabled.

**Allowed values:** `translated`, `original`

**Default:** `translated`

**Note:** If `original` is selected but the original transcription is unavailable, subtitles fall back to `translated`.

**lipSyncMode** `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.

**activeSpeakerDetectionEnabled** `boolean`

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

**Default:** `false`

**lipsyncPro** `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.

> [!WARNING]
>
> **Max duration:** 180 minutes per video.
>
> **Latency:** Lip-sync processing typically adds **2x-4x** the original video duration.

> [!NOTE]
>
> Lip-sync completion and failure emails are not sent for API-triggered requests. Use the [status endpoint](https://api-docs.voicecheap.ai/docs/api-reference/translation-status.md) 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"`).

> [!WARNING]
>
> Do not combine `lipsyncPro` with a conflicting `lipSyncMode`.

**voiceMode** `string`

Voice strategy: `cloning` or `custom`.

**Default:** `cloning`

**voiceId** `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.

**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). A `speakerBoost` value sent by earlier integrations is still accepted but no longer has any effect.

> [!NOTE]
>
> These settings apply only when `voiceMode` is `cloning`.

**voiceCloningSettings properties**

**stability** `number` (default: 0.65)

**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.65`

**similarity** `number` (default: 0.75)

**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.75`

**Default values (balanced):**

```json theme={null}
{
  "stability": 0.6,
  "similarity": 0.8
}
```

**translationTimeSkips** `string`

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

```json theme={null}
[
  { "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](https://api-docs.voicecheap.ai/docs/api-reference/project-details.md).

### 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](https://api-docs.voicecheap.ai/docs/api-reference/translation-status.md) returns HTTP 200 with `status: "failed"` and an `error` containing `code` and `message`; the `project.translation.failed` [webhook](https://api-docs.voicecheap.ai/docs/api-reference/webhooks.md) 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](https://api-docs.voicecheap.ai/docs/api-reference/create-project.md), export its transcript, translate it cue by cue, and call [Dub Project](https://api-docs.voicecheap.ai/docs/api-reference/dub-project.md).

### Checking the pacing

Long sentences must be sped up to fit their segment. Export the translated transcript with
[Export Project Transcript](https://api-docs.voicecheap.ai/docs/api-reference/project-transcript.md): 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.

> [!NOTE]
>
> `translatedSrt` is also accepted on the JSON endpoint [Dub Project](https://api-docs.voicecheap.ai/docs/api-reference/dub-project.md), which dubs an
> existing project that has already been transcribed, without uploading the media again.

## 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*

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

## Examples

> [!NOTE]
>
> Saved glossary rules and custom translation instructions from the effective account or team are applied automatically.

```bash cURL theme={null}
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 "subtitles=true" \
  -F "subtitlesSource=translated" \
  -F "lipSyncMode=standard" \
  -F "activeSpeakerDetectionEnabled=true"
```

```typescript TypeScript theme={null}
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;
  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;
    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?.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,
    subtitles: true,
    subtitlesSource: 'translated',
    voiceCloningSettings: {
      stability: 0.6,
      similarity: 0.85,
    },
  });
  console.log('Project ID:', result.projectId);
}
```

```javascript JavaScript theme={null}
const formData = new FormData();
formData.append('file', videoFile);
formData.append('targetLanguage', 'spanish');
formData.append('projectName', 'My Spanish Translation');
formData.append('keepBackgroundMusic', 'true');
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);
```

```python Python theme={null}
import requests
import json

files = {'file': open('video.mp4', 'rb')}
data = {
    'targetLanguage': 'spanish',
    'projectName': 'My Spanish Translation',
    'keepBackgroundMusic': 'true',
    '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 PHP theme={null}
<?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',
    '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

```json theme={null}
{
  "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` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.