Getting started To get started with the API, you need to obtain an API key. You can create it above on this page. To send requests to the API, use https://app.dubformer.ai as the base URL. Every API request must include an Authorization header with the value Bearer YOUR_API_KEY. Each POST request must include a Content-Type: application/json header and a request body in JSON format. You can use the Idempotency-Key header for POST requests to ensure the uniqueness of the request. Create a project for dubbing POST /api/v1/projects
Creates a dubbing project.
Request Fields:
name (optional): The name of the project.source_lang (required): The source language of the video without locale. Full list can be found in the options .target_lang (required): The target language for the dubbing with locale (e.g. en-US, uk-UA). Full list can be found in the options .source_video_url (required): Direct link to the source video file or YouTube linkmixing_mode (optional): The mixing mode for the voiceover. Possible values:voiceover_only: Only voiceover without the original track.voiceover_with_original_track: Voiceover with the original track.voiceover_without_original_voice: Smart vocal removal voiceover (Dubbing).use_emotional_transfer (optional): Boolean flag to use emotional but less stable soundalike voices.use_soundalike_voices (optional): Boolean flag to use soundalike voices. Subscription only source_script_content (optional): Transcription of the source video in str, vtt or text format. Pro subscription glossary_content (optional): Translation glossary in tsv format Pro subscription Example request
cURL Python Javascript
curl -X POST https://app.dubformer.ai/api/v1/projects \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "My project",
"source_lang": "en",
"target_lang": "fr-FR",
"source_video_url": "https://example.com/video.mp4",
"use_soundalike_voices": true,
"mixing_mode": "voiceover_with_original_track"
}'
import requests
url = 'https://app.dubformer.ai/api/v1/projects'
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
}
data = {
"name": "My project",
"source_lang": "en",
"target_lang": "fr-FR",
"source_video_url": "https://example.com/video.mp4",
"use_soundalike_voices": true,
"mixing_mode": "voiceover_with_original_track"
}
response = requests.request('POST', url, headers=headers, json=data)
print(response.json())
const url = 'https://app.dubformer.ai/api/v1/projects';
const headers = {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
};
const data = {
"name": "My project",
"source_lang": "en",
"target_lang": "fr-FR",
"source_video_url": "https://example.com/video.mp4",
"use_soundalike_voices": true,
"mixing_mode": "voiceover_with_original_track"
};
fetch(url, {
method: 'POST',
headers,
body: JSON.stringify(data),
})
.then(response => response.json())
.then(data => console.log(data));
Example response
{
"project_id": "12345",
"cost_minutes": 10,
"estimated_completion_date": "2024-06-05T12:00:00Z",
"balance_minutes": 90,
"translations_count": 0
}
Get project details GET /api/v1/projects/:id
Retrieves details of a specific project by ID.
Example request
cURL Python Javascript
curl -X GET https://app.dubformer.ai/api/v1/projects/{project_id} \
-H 'Authorization: Bearer YOUR_API_KEY'
import requests
url = 'https://app.dubformer.ai/api/v1/projects/{project_id}'
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
}
response = requests.request('GET', url, headers=headers)
print(response.json())
const url = 'https://app.dubformer.ai/api/v1/projects/{project_id}';
const headers = {
'Authorization': 'Bearer YOUR_API_KEY',
};
fetch(url, {
method: 'GET',
headers,
})
.then(response => response.json())
.then(data => console.log(data));
Example response for ready project
{
"name": "My project",
"source_lang": "en",
"target_lang": "fr-FR",
"mixing_mode": "voiceover_with_original_track",
"cost_minutes": 10,
"created_date": "2024-06-01T12:00:00Z",
"status": "ready",
"completion_date": "2024-06-02T12:00:00Z",
"output_video_url": "https://example.com/output_video.mp4",
"output_tts_audio_url": "https://example.com/output_tts_audio.wav",
"output_source_script": [{ "start_ms": 100, "end_ms": 1544, "text": "Hello world!", speaker_id: 1 }],
"output_target_script": [{ "start_ms": 100, "end_ms": 1544, "text": "Bonjour le monde!", speaker_id: 1 }],
"output_target_speakers": [{ "speaker_id": 1, "voice_key": "voice:Rachel", "style": "feminine" }]
}
Example response for in progress project
{
...
"status": "in_progress",
"estimated_completion_date": "2024-06-05T12:00:00Z"
}
Example response for error project
{
...
"status": "error",
"error_message": "An error occurred during processing."
}
Modify project and re-translate Modifying the project and re-translation is not available to users by default. If you wish to use this feature, please contact us at support@dubformer.ai
POST /api/v1/projects/:id/translations
Creates a new translation for an existing project
Request Fields:
target_script (required): An array of target language script for dubbing. In the same format as output_target_script of the project details .start_ms Start time in milliseconds. Number.end_ms End time in milliseconds. Number.text Text of the translation to synthesize. String.speaker_id Speaker ID. Number.target_speakers (required): An array of target speakers for dubbing. In the same format as output_target_speakers of the project details .speaker_id Speaker ID. Unique number.style Speaker style. Either "masculine" or "feminine".voice_key Voice key. Can be either one of the following values:soundalike for soundalike voices Subscription only emotional_transfer for emotional but less stable soundalike voices.One of the supported voices for the target language from the voices list. mixing_mode (optional): The mixing mode for the voiceover. Possible values:voiceover_only: Only voiceover without the original track.voiceover_with_original_track: Voiceover with the original track.voiceover_without_original_voice: Smart vocal removal voiceover (Dubbing).Example request
cURL Python Javascript
curl -X POST https://app.dubformer.ai/api/v1/projects/{project_id}/translations \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"target_script": [
{
"start_ms": 100,
"end_ms": 1544,
"text": "Au revoir le monde!",
"speaker_id": 1
}
],
"target_speakers": [
{
"speaker_id": 1,
"voice_key": "voice:NewVoice",
"style": "feminine"
}
],
"mixing_mode": "voiceover_only"
}'
import requests
url = 'https://app.dubformer.ai/api/v1/projects/{project_id}/translations'
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
}
data = {
"target_script": [
{
"start_ms": 100,
"end_ms": 1544,
"text": "Au revoir le monde!",
"speaker_id": 1
}
],
"target_speakers": [
{
"speaker_id": 1,
"voice_key": "voice:NewVoice",
"style": "feminine"
}
],
"mixing_mode": "voiceover_only"
}
response = requests.request('POST', url, headers=headers, json=data)
print(response.json())
const url = 'https://app.dubformer.ai/api/v1/projects/{project_id}/translations';
const headers = {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
};
const data = {
"target_script": [
{
"start_ms": 100,
"end_ms": 1544,
"text": "Au revoir le monde!",
"speaker_id": 1
}
],
"target_speakers": [
{
"speaker_id": 1,
"voice_key": "voice:NewVoice",
"style": "feminine"
}
],
"mixing_mode": "voiceover_only"
};
fetch(url, {
method: 'POST',
headers,
body: JSON.stringify(data),
})
.then(response => response.json())
.then(data => console.log(data));
Example response
{
"project_id": "12345",
"cost_minutes": 0,
"estimated_completion_date": "2024-06-05T12:00:00Z",
"balance_minutes": 90,
"translations_count": 1
}
The response is essentially the same as for project creation, but with an increased number of translations. And we don't charge for the re-translation at the moment.
Validate re-translation request POST /api/v1/projects/:id/validate-translation-request
Validates the re-translation request without actually creating a new translation.
Request fields are the same as in the modify project and re-translate request.
Example response for valid request
{
"valid": true
}
Example response for invalid request
{
"error": "ValidationError",
"message": "Unknown voice unknown-voice"
}
Delete a project DELETE /api/v1/projects/:id
Deletes a specific project by ID.
Example request
cURL Python Javascript
curl -X DELETE https://app.dubformer.ai/api/v1/projects/{project_id} \
-H 'Authorization: Bearer YOUR_API_KEY'
import requests
url = 'https://app.dubformer.ai/api/v1/projects/{project_id}'
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
}
response = requests.request('DELETE', url, headers=headers)
print(response.json())
const url = 'https://app.dubformer.ai/api/v1/projects/{project_id}';
const headers = {
'Authorization': 'Bearer YOUR_API_KEY',
};
fetch(url, {
method: 'DELETE',
headers,
})
.then(response => response.json())
.then(data => console.log(data));
Example response
{
"success": true
}
Get all projects GET /api/v1/projects
Retrieves a list of all projects.
Example request
cURL Python Javascript
curl -X GET https://app.dubformer.ai/api/v1/projects \
-H 'Authorization: Bearer YOUR_API_KEY'
import requests
url = 'https://app.dubformer.ai/api/v1/projects'
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
}
response = requests.request('GET', url, headers=headers)
print(response.json())
const url = 'https://app.dubformer.ai/api/v1/projects';
const headers = {
'Authorization': 'Bearer YOUR_API_KEY',
};
fetch(url, {
method: 'GET',
headers,
})
.then(response => response.json())
.then(data => console.log(data));
Example response
{
"projects": [
{
"project_id": "12345",
"name": "Project 1",
"status": "ready",
"source_lang": "en",
"target_lang": "fr-FR",
"cost_minutes": 10,
"created_date": "2024-06-01T12:00:00Z"
},
{
"project_id": "67890",
"name": "Project 2",
"status": "in_progress",
"source_lang": "fr",
"target_lang": "de-DE",
"cost_minutes": 15,
"created_date": "2024-06-02T12:00:00Z"
}
]
}
Get options GET /api/v1/options
Retrieves supported source and target languages.
Example request
cURL Python Javascript
curl -X GET https://app.dubformer.ai/api/v1/options \
-H 'Authorization: Bearer YOUR_API_KEY'
import requests
url = 'https://app.dubformer.ai/api/v1/options'
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
}
response = requests.request('GET', url, headers=headers)
print(response.json())
const url = 'https://app.dubformer.ai/api/v1/options';
const headers = {
'Authorization': 'Bearer YOUR_API_KEY',
};
fetch(url, {
method: 'GET',
headers,
})
.then(response => response.json())
.then(data => console.log(data));
Example response
{
"source_langs": ["ar", "de", "en", ...],
"target_langs": ["af-ZA", "am-ET", "ar-AE", ...]
}
Get supported voices GET /api/v1/voices
Retrieves supported voices for re-translations for all supported languages.
Example request
cURL Python Javascript
curl -X GET https://app.dubformer.ai/api/v1/voices \
-H 'Authorization: Bearer YOUR_API_KEY'
import requests
url = 'https://app.dubformer.ai/api/v1/voices'
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
}
response = requests.request('GET', url, headers=headers)
print(response.json())
const url = 'https://app.dubformer.ai/api/v1/voices';
const headers = {
'Authorization': 'Bearer YOUR_API_KEY',
};
fetch(url, {
method: 'GET',
headers,
})
.then(response => response.json())
.then(data => console.log(data));
Example response
{
"voices": {
"af-ZA": [
{
"name": "Adri",
"voice_key": "53f154:af-ZA-AdriNeural",
"style": "feminine"
},
{
"name": "Willem",
"voice_key": "53f154:af-ZA-WillemNeural",
"style": "masculine"
}
],
...
}
}
Get balance GET /api/v1/balance
Retrieves the current balance in minutes.
Example request
cURL Python Javascript
curl -X GET https://app.dubformer.ai/api/v1/balance \
-H 'Authorization: Bearer YOUR_API_KEY'
import requests
url = 'https://app.dubformer.ai/api/v1/balance'
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
}
response = requests.request('GET', url, headers=headers)
print(response.json())
const url = 'https://app.dubformer.ai/api/v1/balance';
const headers = {
'Authorization': 'Bearer YOUR_API_KEY',
};
fetch(url, {
method: 'GET',
headers,
})
.then(response => response.json())
.then(data => console.log(data));
Example response
{
"balance_minutes": 90
}
Errors The API uses standard HTTP status codes to indicate the success or failure of a request.
The response body may contain additional information about the error in the following format:
{
"error": "SpecificErrorType",
"message": "Human-readable error message"
}
The following error types are possible:
ValidationError: The request body is invalid.PaymentRequiredError: The user has no available minutes.UnauthorizedError: The API key is invalid.VideoInfoError: The video information is invalid.And others...