Dubformer API

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 link
  • 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.
  • 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 -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" }'
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'
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'
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'
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'
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'
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...