> ## 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](/docs/api-reference/translation-status) to track progress and retrieve results. Use [Get Project Details](/docs/api-reference/project-details) when you need translated version history or lip-sync history.

## Concurrency Limit

You can run up to 10 translations at the same time per account. If 10 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

<ParamField header="x-api-key" type="string" required>
  Your VoiceCheap API key. Get one from [app.voicecheap.ai/page-api](https://app.voicecheap.ai/page-api).
</ParamField>

### Body Parameters

<ParamField body="file" type="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`

  **Maximum file size:** 20 GB
</ParamField>

<ParamField body="targetLanguage" type="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`, `punjabi`, `romanian`, `russian`, `serbian`, `slovak`, `slovenian`, `spanish`, `swahili`, `swedish`, `tagalog`, `tamil`, `telugu`, `thai`, `turkish`, `ukrainian`, `urdu`, `vietnamese`, `welsh`, `yoruba`, `zulu`
</ParamField>

<ParamField body="originalLanguage" type="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.
  </Warning>

  **Default:** `auto-detect`
</ParamField>

<ParamField body="projectName" type="string">
  A custom name for the project. Useful for identifying projects in your dashboard.

  **Default:** The project ID will be used if not provided.
</ParamField>

<ParamField body="keepBackgroundMusic" type="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`
</ParamField>

<ParamField body="voiceIsolatorOption" type="string">
  Voice isolation mode when `keepBackgroundMusic` is enabled. Controls the quality and characteristics of voice separation.

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.

    <Warning>This option may create artifacts or unexpected effects in some cases due to the preservation of background elements.</Warning>
  </Accordion>

  **Allowed values:** `studio`, `realistic`

  **Default:** `studio`
</ParamField>

<ParamField body="subtitles" type="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`
</ParamField>

<ParamField body="subtitlesSource" type="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`.
</ParamField>

<ParamField body="lipsyncPro" type="boolean">
  Trigger lip-sync processing after translation completes.

  * `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:** 30 minutes per video.

    **Latency:** Lip-sync processing typically adds **2x-4x** the original video duration.
  </Warning>

  <Info>
    Lip-sync completion and failure emails are not sent for API-triggered requests. Use the [status endpoint](/docs/api-reference/translation-status) to
    track progress.
  </Info>

  **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"`).
</ParamField>

<ParamField body="voiceCloningSettings" type="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).

  <Info>API translations always use voice cloning. These settings tune the generated cloned voice for this API request.</Info>

  <Expandable title="voiceCloningSettings properties">
    <ParamField body="stability" type="number" default="0.60" placeholder="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`

      **Tip:** For avoiding accent reproduction, use `0.80`
    </ParamField>

    <ParamField body="similarity" type="number" default="0.85" placeholder="0.85">
      **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.85`

      **Tip:** For avoiding accent reproduction, use `0.20`
    </ParamField>

    <ParamField body="speakerBoost" type="number" default="0.60" placeholder="0.60">
      **Speaker Boost (0.00 - 1.00)**

      Boosts similarity to the original speaker. This is a subtle enhancement that increases resemblance to the source voice.

      **Note:** Higher values increase compute time and latency.

      **Default:** `0.60`

      **Tip:** For avoiding accent reproduction, use `0.00`
    </ParamField>
  </Expandable>

  **Default values (balanced):**

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

  **Recommended for avoiding accent reproduction:**

  ```json theme={null}
  {
    "stability": 0.8,
    "similarity": 0.2,
    "speakerBoost": 0.0
  }
  ```
</ParamField>

## Response

<ResponseField name="success" type="boolean" required>
  Always `true` for successful requests
</ResponseField>

<ResponseField name="message" type="string" required>
  A human-readable message describing the result
</ResponseField>

<ResponseField name="projectId" type="string" required>
  The unique identifier for the created translation project. Use this ID to check status.
</ResponseField>

<ResponseField name="estimatedDuration" type="number" required>
  Rough processing estimate in minutes. The current estimate is five minutes of processing per started minute of source media.
</ResponseField>

## Examples

<Info>
  `subtitlesSource` accepts `translated` or `original` to control which text is used for subtitles. The public API does not currently expose app-only
  controls such as keeping the original voice bed, custom voice IDs, or translation time skips.
</Info>

<CodeGroup>
  ```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 "keepBackgroundMusic=true" \
    -F "voiceIsolatorOption=studio" \
    -F "subtitles=true" \
    -F "subtitlesSource=translated" \
    -F "lipsyncPro=false"
  ```

  ```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
    speakerBoost: number; // 0.00 - 1.00
  }

  interface StartTranslationRequest {
    targetLanguage: string;
    originalLanguage?: string;
    projectName?: string;
    keepBackgroundMusic?: boolean;
    voiceIsolatorOption?: 'studio' | 'realistic';
    subtitles?: boolean;
    subtitlesSource?: 'translated' | 'original';
    lipsyncPro?: boolean; // false = standard, true = Lip Sync Pro (omit to disable)
    voiceCloningSettings?: VoiceCloningSettings;
  }

  async function startTranslation(
    file: File,
    targetLanguage: string,
    options?: {
      originalLanguage?: string;
      projectName?: string;
      keepBackgroundMusic?: boolean;
      voiceIsolatorOption?: 'studio' | 'realistic';
      subtitles?: boolean;
      subtitlesSource?: 'translated' | 'original';
      lipsyncPro?: boolean;
      voiceCloningSettings?: VoiceCloningSettings;
    },
  ): 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?.keepBackgroundMusic !== undefined) {
      formData.append('keepBackgroundMusic', String(options.keepBackgroundMusic));
    }
    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?.lipsyncPro !== undefined) {
      formData.append('lipsyncPro', String(options.lipsyncPro));
    }
    if (options?.voiceCloningSettings) {
      formData.append('voiceCloningSettings', JSON.stringify(options.voiceCloningSettings));
    }

    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,
        speakerBoost: 0.6,
      },
    });
    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('voiceIsolatorOption', 'studio');
  formData.append('subtitles', 'true');
  formData.append('subtitlesSource', 'translated');
  formData.append(
    'voiceCloningSettings',
    JSON.stringify({
      stability: 0.6,
      similarity: 0.85,
      speakerBoost: 0.6,
    }),
  );

  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',
      'voiceIsolatorOption': 'studio',
      'subtitles': 'true',
      'subtitlesSource': 'translated',
      'voiceCloningSettings': json.dumps({
          'stability': 0.60,
          'similarity': 0.85,
          'speakerBoost': 0.60
      })
  }
  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,
      'speakerBoost' => 0.60
  ]);

  $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'];
  ```
</CodeGroup>

## 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_BOOLEAN_VALUE`                | A boolean parameter has an invalid value (use "true" or "false")      |
| 400    | `INVALID_JSON_FORMAT`                  | The voiceCloningSettings JSON is malformed                            |
| 400    | `LIPSYNC_VIDEO_TOO_LONG`               | Lip-sync was requested for media longer than the supported duration   |
| 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    | `API_ACCESS_REQUIRED`                  | API access is required for this account                               |
| 403    | `SUBSCRIPTION_REQUIRED`                | API access requires a paid subscription                               |
| 403    | `INSUFFICIENT_CREDITS`                 | Not enough credits to process this file                               |
| 429    | `RATE_LIMIT_EXCEEDED`                  | Too many requests (limit: 10 requests per minute)                     |
| 429    | `CONCURRENT_TRANSLATION_LIMIT_REACHED` | Too many translations in progress (limit: 10 concurrent translations) |