API Documentation - DoubleSub.io

Overview

The DoubleSub.io API allows you to programmatically merge two subtitle files into a single bilingual subtitle file. This is useful for building integrations, plugins, or automating subtitle processing.

Base URL: https://doublesub.io

API Key

To use the API, you need an API key. Keys are free and anonymous - no account required!

Limit: 50 merges per day per key.

Merge Subtitles

POST /api/v1/merge

Request Parameters

Content-Type: multipart/form-data

Parameter	Type	Description
api_key required	string	Your API key (also accepted via X-API-Key header)
srt1 required	file	First subtitle file (SRT format) - displayed on top
srt2 required	file	Second subtitle file (SRT format) - displayed on bottom
mode optional	string	Merge mode: `all` (default), `overlapping`, or `primary`
tolerance optional	integer	Timing tolerance in milliseconds (default: 700)
offset1 optional	integer	Time offset for first subtitle in ms (default: 0)
offset2 optional	integer	Time offset for second subtitle in ms (default: 0)
color1 optional	string	HTML color for first subtitle (e.g., #FFFFFF)
color2 optional	string	HTML color for second subtitle (e.g., #FFFF00)
format optional	string	Response format: `file` (default) or `json`

Example: cURL

# Get merged file directly (using header)
curl -X POST https://doublesub.io/api/v1/merge \
  -H "X-API-Key: dsub_your_api_key_here" \
  -F "srt1=@english.srt" \
  -F "srt2=@french.srt" \
  -F "mode=all" \
  --output merged.srt

# Or pass API key in form data
curl -X POST https://doublesub.io/api/v1/merge \
  -F "api_key=dsub_your_api_key_here" \
  -F "srt1=@english.srt" \
  -F "srt2=@french.srt" \
  --output merged.srt

# Get JSON response
curl -X POST https://doublesub.io/api/v1/merge \
  -H "X-API-Key: dsub_your_api_key_here" \
  -F "srt1=@english.srt" \
  -F "srt2=@french.srt" \
  -F "format=json"
            

Example: Python

import requests

url = "https://doublesub.io/api/v1/merge"

headers = {
    'X-API-Key': 'dsub_your_api_key_here'
}

files = {
    'srt1': open('english.srt', 'rb'),
    'srt2': open('french.srt', 'rb')
}

data = {
    'mode': 'all'
}

response = requests.post(url, headers=headers, files=files, data=data)

with open('merged.srt', 'wb') as f:
    f.write(response.content)
            

Example: C# (for Emby plugin)

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "dsub_your_api_key_here");

using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("english.srt")), "srt1", "english.srt");
form.Add(new ByteArrayContent(File.ReadAllBytes("french.srt")), "srt2", "french.srt");
form.Add(new StringContent("all"), "mode");

var response = await client.PostAsync("https://doublesub.io/api/v1/merge", form);
var mergedSrt = await response.Content.ReadAsByteArrayAsync();

File.WriteAllBytes("merged.srt", mergedSrt);
            

Response (format=json)

{
    "success": true,
    "cue_count": 1234,
    "download_url": "/download/api_merged_123456.srt",
    "preview": [
        {
            "index": 1,
            "start": "00:00:01,000",
            "end": "00:00:04,000",
            "text": "Hello\nBonjour"
        }
    ]
}
            

Error Response

{
    "success": false,
    "error": "Two SRT files required (srt1 and srt2)"
}
            

Merge Modes

Mode	Description
all	Include all subtitles from both files. Overlapping subtitles are merged together.
overlapping	Only include subtitles that overlap in timing between both files.
primary	Use timing from the first file. Second file subtitles are matched to first file timing.

Rate Limits

Each API key is limited to 50 merges per day. The limit resets every 24 hours from your first merge.

Need more? Contact us for enterprise solutions or self-host your own instance.

Rate Limit Response

{
    "success": false,
    "error": "Daily limit exceeded (50 merges/day). Resets in 24h.",
    "remaining": 0
}
            