API Documentation
Learn how to use our subtitle translation API
Overview
Our subtitle translation API provides a simple and efficient way to translate various formats of subtitle files. Through RESTful API interfaces, you can easily integrate subtitle translation into your applications or workflows.
The API supports multiple subtitle formats, including SRT, VTT, ASS, etc., and provides mutual translation functions for more than 50 languages. We use advanced neural network translation technology to ensure accurate and natural translation quality.
Please note that using the API requires registering an account and obtaining AppID and AppKey first. Each API request will consume a certain number of Tokens, and the specific consumption depends on the number of characters being translated.
Authentication
All API requests require authentication. You need to include your AppID and AppKey in the request headers so that we can verify your identity and permissions.
Request Headers
| Header | Type | Description | Required |
|---|---|---|---|
| AppID | string | Your application ID | Required |
| AppKey | string | Your application key | Required |
| Content-Type | string | Request content type, usually application/json | Required |
Example
curl -X POST "https://api.subtitle-translation.com/v1/translate" \
-H "AppID: your_app_id" \
-H "AppKey: your_app_key" \
-H "Content-Type: application/json" \
-d '{"text": "Hello world", "source_lang": "en", "target_lang": "zh"}'
API Endpoints
Translate Text
POST/v1/translate/text
Translate single or multiple texts. Suitable for short text translation, such as subtitle lines, titles, etc.
Request Body
{
"texts": ["Hello world", "How are you?"],
"source_lang": "en",
"target_lang": "zh"
}
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| texts | array | Array of texts to translate | Required |
| source_lang | string | Source language code | Required |
| target_lang | string | Target language code | Required |
Response
{
"status": "success",
"data": {
"translations": [
{
"source": "Hello world",
"target": "你好世界",
"source_lang": "en",
"target_lang": "zh"
},
{
"source": "How are you?",
"target": "你好吗?",
"source_lang": "en",
"target_lang": "zh"
}
],
"token_used": 18
}
}
Translate Subtitle File
POST/v1/translate/file
Translate complete subtitle files. Supports multiple subtitle formats, such as SRT, VTT, ASS, etc.
Request Body
Use multipart/form-data format to upload files:
curl -X POST "https://api.subtitle-translation.com/v1/translate/file" \ -H "AppID: your_app_id" \ -H "AppKey: your_app_key" \ -F "file=@subtitle.srt" \ -F "source_lang=en" \ -F "target_lang=zh" \ -F "format=srt"
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| file | file | Subtitle file | Required |
| source_lang | string | Source language code | Required |
| target_lang | string | Target language code | Required |
| format | string | Subtitle format, such as srt, vtt, ass, etc. | Optional |
Response
The response will contain the translated subtitle file content:
{
"status": "success",
"data": {
"translated_content": "1\n00:00:01,000 --> 00:00:03,000\n你好世界\n\n2\n00:00:04,000 --> 00:00:06,000\n你好吗?",
"format": "srt",
"source_lang": "en",
"target_lang": "zh",
"token_used": 18
}
}
Get Balance
GET/v1/balance
Query the current remaining Token balance of your account.
Example
curl -X GET "https://api.subtitle-translation.com/v1/balance" \ -H "AppID: your_app_id" \ -H "AppKey: your_app_key"
Response
{
"status": "success",
"data": {
"balance": 9800,
"currency": "token"
}
}
Supported Languages
Our API supports mutual translation of more than 50 languages. The following is a list of the main supported languages:
| Language | Code | Example |
|---|---|---|
| English | en | Hello world |
| Chinese (Simplified) | zh | 你好世界 |
| Japanese | ja | こんにちは世界 |
| Korean | ko | 안녕하세요 세계 |
| French | fr | Bonjour le monde |
| German | de | Hallo Welt |
| Spanish | es | Hola Mundo |
| Russian | ru | Привет мир |
For a complete list of languages, please contact our technical support team.
Subtitle Formats
Our API supports multiple common subtitle formats. The following is a list of the main supported formats:
SRT
SubRip subtitle format, one of the most commonly used subtitle formats.
1 00:00:01,000 --> 00:00:03,000 Hello world 2 00:00:04,000 --> 00:00:06,000 How are you?
VTT
WebVTT subtitle format, the standard subtitle format for HTML5 videos.
WEBVTT 1 00:00:01.000 --> 00:00:03.000 Hello world 2 00:00:04.000 --> 00:00:06.000 How are you?
ASS
Advanced SubStation Alpha format, supporting advanced styles and effects.
[Script Info] Title: Example ScriptType: v4.00+ PlayResX: 800 PlayResY: 450 [V4+ Styles] Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding Style: Default,Arial,20,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,2,2,10,10,10,0 [Events] Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text Dialogue: 0,0:00:01.00,0:00:03.00,Default,,0,0,0,,Hello world Dialogue: 0,0:00:04.00,0:00:06.00,Default,,0,0,0,,How are you?
SSA
SubStation Alpha format, the predecessor of the ASS format.
[Script Info] Title: Example ScriptType: v4.00 PlayResX: 800 PlayResY: 450 [V4 Styles] Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, TertiaryColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding Style: Default,Arial,20,16777215,0,0,0,0,0,0,0,100,100,0,0,1,2,2,2,10,10,10,0 [Events] Format: Marked, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text Dialogue: Marked=0,0:00:01.00,0:00:03.00,Default,,0,0,0,,Hello world Dialogue: Marked=0,0:00:04.00,0:00:06.00,Default,,0,0,0,,How are you?
Error Handling
When an API request fails, we will return the corresponding error code and error message to help you quickly locate and solve the problem.
| Error Code | Description | Solution |
|---|---|---|
| 400 | Bad Request | Check if the request parameters are correct and ensure all required parameters are provided |
| 401 | Unauthorized | Check if the AppID and AppKey are correct |
| 403 | Insufficient Token Balance | Recharge Token and try again |
| 404 | API Endpoint Not Found | Check if the API endpoint URL is correct |
| 413 | Request Entity Too Large | Reduce the size of the request body or split large files into multiple small files |
| 500 | Internal Server Error | Try again later or contact technical support |
Error Response Example
{
"status": "error",
"code": 401,
"message": "Invalid AppID or AppKey"
}
Example Code
The following are example codes for calling our API using different programming languages:
JavaScript Example
// Using Fetch API to translate text
async function translateText() {
const response = await fetch('https://api.subtitle-translation.com/v1/translate/text', {
method: 'POST',
headers: {
'AppID': 'your_app_id',
'AppKey': 'your_app_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
texts: ['Hello world', 'How are you?'],
source_lang: 'en',
target_lang: 'zh'
})
});
const data = await response.json();
console.log(data);
}
// Using Fetch API to upload subtitle file
async function translateFile(file) {
const formData = new FormData();
formData.append('file', file);
formData.append('source_lang', 'en');
formData.append('target_lang', 'zh');
const response = await fetch('https://api.subtitle-translation.com/v1/translate/file', {
method: 'POST',
headers: {
'AppID': 'your_app_id',
'AppKey': 'your_app_key'
},
body: formData
});
const data = await response.json();
console.log(data);
}