VideoDubber Developers API

VideoDubber API

Programmatically translate video or audio by submitting a public media URL to api.videodubber.ai, then polling until the translated file is ready. Official Python and JavaScript clients handle auth, throttling, and polling.

Requirements

• A VideoDubber API key (included on paid plans)
• A stable, publicly reachable http or https URL to the source media
• Python 3.10+ for the Python client (requests installed automatically)
• Node.js 18+ for the JavaScript client (native fetch)

Quickstart

The fastest path is an official client — it handles throttling, retries, and polling. Or integrate directly with REST: create a job, save the pid, then poll status every 15 seconds until status is complete.

Python

pip install videodubber
export VIDEODUBBER_API_KEY="your-api-key"

videodubber \
  --file-url "https://example.com/video.mp4" \
  --target-language Spanish \
  --voice Elvira \
  --output ./translated.mp4

JavaScript / TypeScript

npm install videodubber
export VIDEODUBBER_API_KEY="your-api-key"

npx videodubber \
  --file-url "https://example.com/video.mp4" \
  --target-language Spanish \
  --voice Elvira \
  --output ./translated.mp4

REST (curl)

1. Create a translation job:

export VIDEODUBBER_API_KEY="your-api-key"

curl -sS -X POST "https://api.videodubber.ai/api/p/jobs" \
  -H "x-api-key: $VIDEODUBBER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/video.mp4",
    "filetype": "mp4",
    "OriginalLanguage": "English",
    "TargetLanguage": "Spanish",
    "NumSpeakers": "1",
    "projectname": "API Project",
    "selectedvoices": ["Elvira"],
    "speakers": ["Speaker 1"],
    "audioshift": "0",
    "translator": "auto",
    "has_subtitle_file": "false",
    "subtitle_language_type": "",
    "glossary_id": "",
    "bg1": "Auto (Not recommended)",
    "bg2": "0",
    "voice_cloning": false
  }'

Success returns HTTP 202 with a project id:

{
  "status": "accepted",
  "pid": "abc123...",
  "project_path": "/path/on/server"
}

2. Poll until complete:

curl -sS "https://api.videodubber.ai/api/p/jobs/YOUR_PID/status" \
  -H "x-api-key: $VIDEODUBBER_API_KEY"

When status is complete, download from output_urls.translated_media. Wait at least 12 seconds between API calls (15 s recommended) to stay under rate limits.

Authentication

Every request to /api/p/* endpoints must include your API key in the x-api-key header.

Getting an API key

API access is included on paid plans. Once subscribed:

1. Log in to app.videodubber.ai
2. Open API Keys in your account dashboard
3. Click Generate API key and copy the key immediately — it is shown once
4. Store the key securely (password manager or secrets vault)

Manage keys via the API

While authenticated with a logged-in session:

Using your key

Optional base URL override (default https://api.videodubber.ai):

export VIDEODUBBER_API_BASE="https://api.videodubber.ai"
# or: --base-url "https://api.videodubber.ai"

How the workflow works

Two steps: submit a job with a public media URL, then poll status until translation finishes or fails.

POST /api/p/jobs

Endpoint: POST https://api.videodubber.ai/api/p/jobs

Required JSON fields

Common optional fields

Example request body

{
  "file_url": "https://example.com/video.mp4",
  "filetype": "mp4",
  "OriginalLanguage": "English",
  "TargetLanguage": "Spanish",
  "NumSpeakers": "1",
  "projectname": "API Project",
  "selectedvoices": ["Elvira"],
  "speakers": ["Speaker 1"],
  "audioshift": "0",
  "translator": "auto",
  "has_subtitle_file": "false",
  "subtitle_language_type": "",
  "glossary_id": "",
  "bg1": "Auto (Not recommended)",
  "bg2": "0",
  "voice_cloning": false
}

Success response (HTTP 202)

{
  "status": "accepted",
  "pid": "abc123...",
  "project_path": "/path/on/server"
}

GET /api/p/jobs/{pid}/status

Endpoint: GET https://api.videodubber.ai/api/p/jobs/{pid}/status

Poll until status is complete or failed.

Processing statuses

When complete, the response includes output_urls.translated_media — a URL to download the translated file. The response may also include available_minutes for credit balance checks.

Rate limits

Limits apply per API key (x-api-key), not per IP address.

Server limits

Polling interval

Wait at least 12 seconds between any two /api/p/* calls. The official Python and JavaScript clients enforce this automatically. One typical job uses roughly 1 create + N status polls (e.g. a 5-minute job ≈ 21 calls at 15 s spacing).

Official client protections

1. Proactive throttling — waits until 12 s have passed since the last API call before each request.

2. Automatic retry on 429 — reads Retry-After from headers or JSON, sleeps, then retries (exponential backoff up to 120 s, 8 attempts by default).

Planning concurrent jobs

For multiple concurrent jobs, use separate API keys or serialize creates with ≥12 s between submits.

File limits

Source media must be reachable by the VideoDubber server over the public internet.

Source file requirements (paid accounts)

file_url must point directly to the media file (e.g. a signed S3/GCS link or direct .mp4 link). YouTube watch links are rejected with HTTP 400 (YouTube URLs are not supported).

Python CLI

Install the official PyPI package for throttling, 429 retries, polling, and optional download. Requires Python 3.10+.

Install

pip install videodubber

Basic example

export VIDEODUBBER_API_KEY="your-uuid-key"

videodubber \
    --file-url "https://example.com/video.mp4" \
    --original-language English \
    --target-language Spanish \
    --voice Elvira \
    --output ./translated.mp4

Multiple speakers

videodubber \
    --file-url "https://example.com/interview.mp4" \
    --target-language French \
    --num-speakers 2 \
    --voice Denise \
    --voice Henri \
    --speaker "Speaker 1" \
    --speaker "Speaker 2"

JSON output (automation)

videodubber \
    --file-url "https://example.com/video.mp4" \
    --target-language German \
    --voice Katja \
    --json \
    --quiet

Prints the final status object to stdout; progress logs go to stderr unless --quiet.

Required CLI arguments

Exit codes

Using as a Python library

Install from PyPI:

pip install videodubber

from videodubber import VideoDubberClient, TranslationJobParams

client = VideoDubberClient(api_key="your-uuid-key")

params = TranslationJobParams(
    file_url="https://example.com/video.mp4",
    target_language="Spanish",
    original_language="English",
    selectedvoices=["Elvira"],
    speakers=["Speaker 1"],
    filetype="mp4",
)

# Submit + poll until complete
status = client.translate_from_url(params, poll_interval=15, max_wait=3600)

print(status.translated_media_url)

Library methods

Node.js CLI

Install the official npm package for throttling, 429 retries, polling, and optional download. Requires Node.js 18+.

Install

npm install videodubber

Basic example

export VIDEODUBBER_API_KEY="your-uuid-key"

npx videodubber \
    --file-url "https://example.com/video.mp4" \
    --original-language English \
    --target-language Spanish \
    --voice Elvira \
    --output ./translated.mp4

Multiple speakers

npx videodubber \
    --file-url "https://example.com/interview.mp4" \
    --target-language French \
    --num-speakers 2 \
    --voice Denise \
    --voice Henri \
    --speaker "Speaker 1" \
    --speaker "Speaker 2"

JSON output (automation)

npx videodubber \
    --file-url "https://example.com/video.mp4" \
    --target-language German \
    --voice Katja \
    --json \
    --quiet

Prints the final status object to stdout; progress logs go to stderr unless --quiet.

Required CLI arguments

Exit codes

Using as a JavaScript / TypeScript library

Install from npm:

npm install videodubber

import { VideoDubberClient } from "videodubber";

const client = new VideoDubberClient({ apiKey: "your-uuid-key" });

const status = await client.translateFromUrl({
  fileUrl: "https://example.com/video.mp4",
  targetLanguage: "Spanish",
  originalLanguage: "English",
  selectedVoices: ["Elvira"],
  speakers: ["Speaker 1"],
  filetype: "mp4",
}, { pollInterval: 15, maxWait: 3600 });

console.log(status.translatedMediaUrl);

Library methods

Common errors

Structured validation errors list accepted languages or voices in the response body.

The official clients print hints for validation errors (accepted languages, accepted voices). Other errors appear as error: ... on stderr.

Integration tips

• Host media on a stable, publicly reachable URL before calling the API. The server downloads the file; private or expiring links often fail.
• Use the client's --output flag to save translated media locally after completion.
• For long jobs, increase --max-wait (default 3600 seconds / 1 hour).
• Run with --debug while integrating to inspect raw status JSON on each poll.
• Do not run many parallel jobs on a single API key — they share the 5/minute rate limit.
• Pass regional language names exactly, e.g. Spanish (Spain), French (France), English (US).