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.
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 onlysource_script_content (optional): Transcription of the source video in str, vtt or text format. Pro subscriptionglossary_content (optional): Translation glossary in tsv format Pro subscription
Example request
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
}
Get project details
GET /api/v1/projects/:id
Retrieves details of a specific project by ID.
Example request
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_url": "https://example.com/source_script.json",
"output_target_script_url": "https://example.com/target_script.json"
}
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."
}
Delete a project
DELETE /api/v1/projects/:id
Deletes a specific project by ID.
Example request
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 -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 -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 balance
GET /api/v1/balance
Retrieves the current balance in minutes.
Example request
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...