Subtitle Tool & Converter
This is the official API to our Subtitle Tool & Converter.
Quick Start
Convert subtitle files to other file formats or use the tool to check subtitles for guidelines, repair or correct them.
Endpoint
This endpoint is used to convert subtitle files.
POST https://api.editingtools.io/v2/subtitles
Authentication
This API requires Basic Authentication. The "Authorization" header should be set with the Base64 encoded string of "apikey:YOUR_API_KEY".
Authorization: Basic <base64Encoded(apikey:YOUR_API_KEY)>
Headers
Content-Type: multipart/form-data
Specifies the format of the request body.
Authorization: Basic <base64EncodedString>
Authentication credential.
Request Body
The request can contain the following parameters:
Parameter | Type | Required | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
file |
File | Yes | Path to your subtitle file. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
source |
String | Yes | The source format of your file. Possible values:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
format |
String | Yes | The target format. Possible values:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
framerate |
String | Yes | The framerate of the marker file. If there is no value set, 25 will be used as default value.Allowed values:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
base64 |
Boolean | No | If set to true , the generated file will be returned as base64 string. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
removeEmpty |
Boolean | No | Recommended: true This removes all subtitles without content. Set to true to activate this option. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
mergeIdentical |
Boolean | No | Recommended: true This merges subtitles with the same text that that follow directly after each other. Set to true to activate this option. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
removeSuperfluousSpaces |
Boolean | No | Recommended: true This replaces multiple spaces in a subtitle with a single space and strips whitespace from the beginning and end of a line. Set to true to activate this option. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
fixInvalidTags |
Boolean | No | Recommended: true This fixes broken tags. Set to true to activate this option. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
removeDurationZero |
Boolean | No | Recommended: true This removes subtitles that have no duration. Set to true to activate this option. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
fixOverlapping |
Boolean | No | Recommended: true This fixes Start and End Timecode of overlapping subtitles. Set to true to activate this option. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
removeRepeatingLines |
Boolean | No | This removes any repeating lines within the one subtitle. Set to true to activate this option. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
removeLineBreaks |
Boolean | No | This removes any linebreaks in all subtitle. Set to true to activate this option. |
There are more options to choose, please contact our free support for more details how to use them.
cURL Examples
The following examples show how to use the API with cURL commands. If you are using a different language, we recommend using https://curlconverter.com to convert the commands for other languages like: PHP, JavaScript, Python, Ruby, Rust, Ansible, C , C#, ColdFusion, Clojure, Dart, Elixir, Go, HAR, HTTP, HTTPie, Java, JSON, Kotlin, MATLAB, Node.js, Objective-C, OCaml, PowerShell, R, Swift and more.
cURL Request Example 1
This is an example of how to convert a subtitle file (SRT to CSV).
curl -X POST https://api.editingtools.io/v2/subtitles \
-u "apikey:YOUR_API_KEY" \
-F file=@/path/to/subtitle.srt \
-F source=srt \
-F format=csv \
-F framerate=25 \
-F removeEmpty=true \
-F mergeIdentical=true \
-F removeSuperfluousSpaces=true \
-F fixInvalidTags=true \
-F removeDurationZero=true \
-F fixOverlapping=true
cURL Request Example 2
This is an example of how to convert a subtitle file and return the output as a Base64 string.
curl -X POST https://api.editingtools.io/v2/subtitles \
-u "apikey:YOUR_API_KEY" \
-F file=@/path/to/subtitle.srt \
-F source=srt \
-F format=csv \
-F framerate=25 \
-F removeEmpty=true \
-F mergeIdentical=true \
-F removeSuperfluousSpaces=true \
-F fixInvalidTags=true \
-F removeDurationZero=true \
-F fixOverlapping=true \
-F base64=true
Responses
Success (HTTP 200 OK)
If the file was successfully converted, the API will return a 200 OK
status code with a JSON object containing the file details.
Field | Type | Description |
---|---|---|
code |
String | HTTP status code. |
status |
String | A message about the request. |
timestamp |
String | Timestamp from server. |
data |
Object | An object containing details about the converted file. |
data.fileName |
String | Name of generated file. |
data.fileBase64 |
String | File encoded as Base64 string. Only if bas64 option is set to true. |
data.fileUrl |
String | Download path of the generated file. |
data.fileSize |
Int | Size of the generated file in bytes. |
data.fileChecksum |
String | MD5 hash of the generated file for validation. |
Response Example 1
The request returns the path to the file.
{
"code": 200,
"status": "Success",
"timestamp": "2025-05-22T19:29:27Z",
"data": {
"fileName": "mysubtitle.csv",
"fileUrl": "https://editingtools.io/path/to/file/mysubtitle.csv",
"fileSize": 1504,
"fileChecksum": "3e85da48d39823444424aba2f41a57db"
}
}
Response Example 2
The request returns the file as Base64 string.
{
"code": 200,
"status": "Success",
"timestamp": "2025-05-22T19:29:27Z",
"data": {
"fileName": "mysubtitle.csv",
"fileBase64": "Tm8sVGltZWNvZGUgSW4sVGltZW...jE3OjIzIiwiMDA6MDA6MTMsM",
"fileSize": 1504,
"fileChecksum": "3e85da48d39823444424aba2f41a57db"
}
}
Error Responses
Error responses typically include an appropriate HTTP status code and a JSON body containing an error message.
{
"code": "400",
"status": "Bad Request",
"timestamp": "2025-05-22T19:29:27Z"
}
Download File
After the process is successfully completed, the file can be downloaded using the values returned under fileUrl
and fileName
. The generated file will be online for a maximum of 20 minutes. After download, you can validate the file with the MD5 hash provided in fileChecksum
.
cURL Request Example (macOS or Linux)
Example to download the file to the Desktop. Uses -o
to specify the output file path.
curl -o ~/Desktop/{fileName} "{fileUrl}"
curl -o ~/Desktop/mysubtitle.csv "https://editingtools.io/path/to/file/mysubtitle.csv"
cURL Request Example (Windows with PowerShell)
curl -o "$env:USERPROFILE\Desktop\{fileName}" "{fileUrl}"
curl -o "$env:USERPROFILE\Desktop\mysubtitle.csv" "https://editingtools.io/path/to/file/mysubtitle.csv"
cURL Request Example (Windows Command Prompt with cURL installed)
curl -o "%USERPROFILE%\Desktop\{fileName}" "{fileUrl}"
curl -o "%USERPROFILE%\Desktop\mysubtitle.csv" "https://editingtools.io/path/to/file/mysubtitle.csv"
Python3 Request Example
import os
import urllib.request
name = "mysubtitle.csv"
url = "https://editingtools.io/path/to/file/mysubtitle.csv"
# Construct the path to the Desktop for example
local_path = os.path.join(os.path.expanduser("~"), "Desktop", name)
# Download the file
try:
urllib.request.urlretrieve(url, local_path)
print(f"File downloaded successfully and saved to: {local_path}")
except Exception as e:
print(f"Failed to download file: {e}")
wget Request Example (macOS or Linux)
Example to download the file to the Desktop. Uses -O
to specify the output file path.
wget -O ~/Desktop/{fileName} "{fileUrl}"
wget -O ~/Desktop/mysubtitle.csv "https://editingtools.io/path/to/file/mysubtitle.csv"
wget Request Example (Windows with PowerShell)
wget -O "$env:USERPROFILE\Desktop\{fileName}" "{fileUrl}"
wget -O "$env:USERPROFILE\Desktop\mysubtitle.csv" "https://editingtools.io/path/to/file/mysubtitle.csv"
wget Request Example (Windows Command Prompt with wget installed)
wget -O "%USERPROFILE%\Desktop\{fileName}" "{fileUrl}"
wget -O "%USERPROFILE%\Desktop\mysubtitle.csv" "https://editingtools.io/path/to/file/mysubtitle.csv"
Endpoint URL
Endpoint URL to convert subtitle files.
https://api.editingtools.io/v2/subtitles
Authentication
This API requires Basic Authentication. The "Authorization" header should be set with the Base64 encoded string of "apikey:YOUR_API_KEY".
Authorization: Basic <base64Encoded(apikey:YOUR_API_KEY)>
Data Handling
Request parameters must be UTF-8 encoded. Results are returned as UTF-8-encoded JSON. By default, datasets will be inside the data tag.
Error Handling
This API service uses standard HTTP response codes to indicate whether a method was completed successfully. HTTP response codes in the 2XX range indicate success. Responses in the 4XX range indicate some sort of failure, while responses in the 5XX range indicate an internal system error that cannot be resolved by the user. The following error codes are used by the API:
Code | Description |
---|---|
200 | OK. The request was successful. |
201 | Created. The entity was created. |
202 | Accepted. The request was accepted. |
400 | Bad request. Please check error message. |
401 | Unauthorized: Username or Api Key is not valid. |
402 | Upgrade Required: This feature requires an active Pro subscription. |
403 | Forbidden: The request is understood, but it has been refused or access is not allowed. |
404 | Not found: The URI requested is invalid or the resource does not exist. |
422 | Unprocessable Entity. A process failed. |
429 | Too Many Requests. Try again in some seconds. |
500 | Internal Server Error. Something is broken. |
502 | Bad Gateway. API is down. |
503 | Service Unavailable. API is up but overloaded with requests. |
504 | Gateway Timeout: API is up but requests reached timout. |
Rate Limits
To prevent abuse and spam, the API has limits at various levels. If you receive error code 429 (Too Many Requests)
, it means you have reached a rate limit.
If you receive a rate limit error, you should stop making requests temporarily. If the retry-after
response header is present, you should not retry your request until after that many seconds has elapsed. To prevent rate-errors, we recommend to wait 300 ms
to 800 ms
between requests to the same endpoint.
Also there is a general limit to the api and all requests made:
Limit | Requests |
---|---|
General limit per minute | 50 |
General limit per hour | 1000 |
Recommended wait time between requests | > 200 ms |
Recommended wait time between requests to one endpoint | > 600 ms |
The general limits per minute and per hour can be changed upon request.
Upload Limits
The maximum upload size for any single request — including file uploads — is 100 MB
. This is a hard limit and applies regardless of your API plan or usage level.
If your request exceeds this size, it will be rejected before reaching our servers. To ensure successful uploads:
- Make sure uploaded files are under 100 MB.
- For larger media, consider splitting files before upload.
- Requests close to the limit may still fail due to encoding or header overhead.
Timezone
This API endpoint returns the time as an ISO 8601 timestamp
in the UTC time zone. These timestamps look like 2025-01-10T15:05:06Z
.
Localization and Languages
This API supports multiple languages. For instance, it can display the text of a status message in a different language.
Accept-Language: LANGUAGE
Example
To set the preferred response language to Spanish, add this header:
Accept-Language: es
cURL Example
To apply the language in a cURL request, add the following header:
-H "Accept-Language: es"
Available Languages
The following list contains all the currently available languages. Note that setting a language header does not guarantee a translated response, as not all texts are translated. If no language is set or a translation is unavailable, the default response will be in English.
Code | Language |
---|---|
en | English |
de | German |
fr | French |
es | Spanish |
ru | Russian |
it | Italian |
el | Greek |
pl | Polish |
pt | Portuguese |
lt | Lithuanian |
ko | Korean |
ja | Japanese |
zh | Chinese |
id | Indonesian |
tr | Turkish |
nl | Dutch |
ro | Romanian |
fi | Finnish |
cs | Czech |
hu | Hungarian |
ar | Arabic |
nb | Norwegian Bokmål |
sk | Slovak |
sl | Slovenian |
sv | Swedish |
lv | Latvian |
et | Estonian |
bg | Bulgarian |
uk | Ukrainian |
da | Danish |