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

# Video Translation API Overview

> Comprehensive guide to the Video Translation API for multilingual video content

> [!WARNING]
>
> The resources (image, video, voice) generated by our API are valid for 7 days.
> Please save the relevant resources as soon as possible to prevent expiration.

> [!NOTE]
>
> Experience our video translation technology in action by exploring our interactive demo on GitHub: [AKool Video Translation Demo](https://github.com/AKOOL-Official/akool-video-translation-demo).

## API Endpoints

### Translation Operations

* [Create Video Translation](https://docs.akool.com/ai-tools-suite/video-translation/create-translation.md) - Translate videos into multiple languages and lip-sync
* [Get Translation Result](https://docs.akool.com/ai-tools-suite/video-translation/get-result.md) - Check processing status and retrieve translated video URLs

### Resource Management

* [Get Language List](https://docs.akool.com/ai-tools-suite/video-translation/get-languages.md) - Get supported languages for translation

## Getting Started

### Basic Workflow

1. **Get Available Languages**:
   * Use the [Get Language List API](https://docs.akool.com/ai-tools-suite/video-translation/get-languages.md) to see all supported target languages
   * Review the [automatic voice selection rules](https://docs.akool.com/ai-tools-suite/video-translation/create-translation.md#voice-selection) for each target language

2. **Create Translation**:
   * Call the [Create Video Translation API](https://docs.akool.com/ai-tools-suite/video-translation/create-translation.md) with your video URL
   * Set `source_language` to "DEFAULT" for automatic language detection
   * Specify target languages and optional voice mappings
   * Configure additional options like lip-sync, captions, and background music removal

3. **Monitor Progress**:
   * Use the [Get Translation Result API](https://docs.akool.com/ai-tools-suite/video-translation/get-result.md) to check processing status
   * Download the translated video URL when status reaches "Completed" (status = 3)

### Key Features

#### Automatic Language Detection

Set `source_language` to "DEFAULT" to automatically detect the original language of your video content.

#### Multiple Language Translation

Translate to multiple languages simultaneously by providing comma-separated language codes in the `language` parameter.

#### Lip-Sync Technology

Enable `lipsync` to synchronize mouth movements with the translated audio for more natural-looking results.

#### Caption Support

Add, translate, or replace subtitles with various caption handling options.

#### Advanced Translation Controls

Fine-tune translations with custom word mappings, pronunciation corrections, and translation styles.

## Response Code Description

> [!NOTE]
>
> Please note that if the value of the response code is not equal to 1000, the request
> has failed or encountered an error.

| **Code** | **Description** |
| - | - |
| 1000 | Success |
| 1003 | Parameter error or Parameter cannot be empty |
| 1008 | The content you requested does not exist |
| 1009 | You do not have permission to perform this operation |
| 1101 | Invalid authorization or The request token has expired |
| 1102 | Authorization cannot be empty |
| 1200 | The account has been banned |
| 1201 | Create audio error, please try again later |
| 1202 | The same video cannot be translated with lip-sync in the same language more than once |
| 1203 | Video should contain audio |
| 1204 | Video duration exceeds 60 seconds (legacy `/content/video/translate` endpoint only; not enforced by `/content/video/createbytranslate`) |
| 1205 | Create video error, please try again later |
| 1207 | The video you are using exceeds the size limit of 300MB |
| 1209 | Please upload a video in another encoding format |
| 1210 | The video you are using exceeds the frame rate limit of 30fps |

## Video Translation Status Codes

When checking results, the `video_status` field indicates the current processing state:

| **Status** | **Description** |
| - | - |
| 1 | Queueing - Your request is waiting to be processed |
| 2 | Processing - Video translation is currently being generated |
| 3 | Completed - Translation finished successfully, video URL is available |
| 4 | Failed - Translation failed, check error details for more information |

## Best Practices

### Video Requirements

* **Duration**: `/content/video/createbytranslate` does not enforce a 60-second limit in OpenAPI validation. Shorter videos are recommended for faster processing; under 60 seconds is a recommendation, not a requirement. The legacy `/content/video/translate` endpoint rejects videos longer than 60 seconds.
* **Size**: Maximum file size is 300MB
* **Frame Rate**: Maximum 30fps supported
* **Audio**: Ensure your video contains clear audio for accurate translation
* **Encoding**: Use standard encoding formats (H.264 recommended)

### Translation Quality Tips

* **Clear Speech**: Videos with clear, well-articulated speech produce better translations
* **Background Noise**: Consider using `remove_bgm: true` to remove background music for clearer voice translation
* **Speaker Count**: Specify the correct number of speakers for better voice separation

### API Usage Tips

* **Webhook**: Use the `webhookUrl` parameter to receive notifications when processing is complete
* **Batch Processing**: For multiple videos, process them in parallel but monitor your quota usage
* **Error Handling**: Implement proper retry logic for failed translations
* **Result Management**: Download and save translated videos promptly as they expire after 7 days

## Common Use Cases

### Single Language Translation

```json theme={null}
{
  "url": "https://example.com/my-video.mp4",
  "source_language": "DEFAULT",
  "language": "es",
  "lipsync": true
}
```

### Multi-Language Translation

```json theme={null}
{
  "url": "https://example.com/my-video.mp4",
  "source_language": "DEFAULT",
  "language": "es,fr,de",
  "lipsync": false,
  "caption_type": 2,
  "remove_bgm": true
}
```

### Professional Translation with Advanced Controls

```json theme={null}
{
  "url": "https://example.com/business-video.mp4",
  "source_language": "DEFAULT",
  "language": "zh-CN",
  "lipsync": true,
  "studio_voice": {
    "style": "professional",
    "no_translate_words": ["AKool", "API"],
    "fixed_words": {"hello": "您好"}
  },
  "caption_type": 3,
  "webhookUrl": "https://your-server.com/webhook"
}
```

## Support

For additional help and examples, check out our:

* [GitHub Demo](https://github.com/AKOOL-Official/akool-video-translation-demo)
* [Authentication Guide](https://docs.akool.com/authentication/usage.md)
* [Webhook Documentation](https://docs.akool.com/ai-tools-suite/webhook.md)


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