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);
}