Skip to main content

Dubly API: documentation, tokens and what you can do

Find the Dubly API documentation, create an API token, and see what the public API can do: create dubs, check their status and start Lip-Sync.

Dubly has a public API that lets you create dubs from your own tools and fetch the finished videos. Every Dubly account can use it. The full documentation is in the app, under Settings → API. This article shows you how to get started and what the API covers.


Where to find the documentation

Open Settings → API and scroll past your tokens to API Documentation. You'll find:

  • Authentication, base URL and response format

  • Every endpoint with its parameters and copy-ready examples

  • Error codes

  • Supported target languages

You need to be signed in to see it. The documentation is available in English only.


Create an API token

Only Owners and Admins can create and revoke tokens.

  1. Open Settings → API.

  2. Click Generate new token and give it a name, e.g. "Production".

  3. Copy it straight away. It is shown only once and cannot be displayed again.

A token stays valid until you revoke it. Anyone who has it can create dubs and spend credits in your account, so treat it like a password. To revoke one, click Revoke next to the token. Any tool using it loses access.


What the API can do

The base URL is https://app.dubly.ai. Every request needs this header: Authorization: Bearer YOUR_API_TOKEN.

Endpoint

What it does

POST /api/v1/dubs/youtube

Creates a dub from a YouTube link.

POST /api/v1/dubs/url

Creates a dub from a direct link to a video file. The link must return the file itself, not a preview page.

POST /api/v1/dubs/google-drive

Creates a dub from a single Google Drive file. Sharing must be set to "Anyone with the link", with downloading allowed.

GET /api/v1/dubs/{id}

Shows the status of a dub and, once it is finished, the video links.

POST /api/v1/dubs/{id}/lipsync

Starts Lip-Sync for one target language of a finished dub.

GET /api/v1/dubs/{id}/lipsync?target_language=de

Shows the Lip-Sync status and, once it is finished, the video link.

GET /api/v1/projects

Lists your projects. Use an ID as project_id to put a dub into that project.

GET /api/v1/custom-voices

Lists the custom voices set up for your account. Use an ID as custom_voice_id.

Language codes are the short ones, such as en, de or fr. See Supported languages and dialects.


Example: create a dub and get the result

Create the dub:

curl -X POST https://app.dubly.ai/api/v1/dubs/youtube \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"yt_link": "https://www.youtube.com/watch?v=VIDEO_ID",
"source_language": "en",
"target_languages": ["de", "fr"]
}'

The response contains the ID of the new dub. Use it to check the status:

curl https://app.dubly.ai/api/v1/dubs/DUB_ID \
-H "Authorization: Bearer YOUR_API_TOKEN"

The status is one of these:

Status

Meaning

Processing

The dub is still running.

Dubbed

The dub is finished. url contains one video link per target language.

Error

The dub failed.

The API has no webhooks, so your tool needs to ask for the status itself. Dubs take a while (see How long does it take to dub a video?), so there is no need to check every few seconds.

Dubs created through the API show up in your Dubly account like any other dub, so you can review and edit them there.


How credits work with the API

  • YouTube and Google Drive: the full cost is charged when the dub is created, based on the length of the video.

  • Direct links: 1 credit per target language is charged at the start, and the rest once the length of the video is known. If your balance can't cover the rest, the dub ends with the status Error.

  • Target languages: each one is billed separately. See Pricing Model and Translation Costs.

  • Lip-Sync: 1 credit per minute of video and target language, rounded up.

  • Free trial: dubs are limited to the first minute, just like in the app.


What the API can't do

  • Upload a file directly. The video has to come from a YouTube link, a Google Drive file or a direct link. See Upload a video: supported formats.

  • Process Google Drive folders. Each file needs its own request.

  • Edit a dub. Translations and voices are edited in the app.

  • Download subtitles. The API only returns video links.

  • List or delete dubs. You can only look up a dub by its ID.


Error codes

Every error response includes a message field with the exact reason.

Status

Meaning

400

The request is invalid, e.g. a required field is missing, a language code isn't available, or the dub isn't finished yet.

401

The token is missing, wrong or revoked.

403

There aren't enough credits, or the token isn't allowed to do this.

404

The dub, YouTube video or Google Drive file wasn't found or isn't available.

409

Lip-Sync is already running, its audio isn't ready yet, or a previous run failed. If a previous run failed, contact support.

500

Something went wrong on our side, or Google Drive couldn't be reached. Try again later.


Dubbing many videos at once

The API takes one request per video. See Dub multiple videos at once. For large or one-off batches, we can run it for you: Requesting a custom batch project.

Still stuck? Contact support and include the dub ID and the error message.

Did this answer your question?