ELelevenlabs
Dubbing

Create Dubbing Project

Changed on

Create a dubbing project from an uploaded file (file) or a source URL (source_url).

Returns as soon as the project record exists, before the source has been fetched: the project starts queued and reaches ready once its source has been transcribed. Add a language target to it for each language you want, or pass target_language to queue the first one here.

Creating a project incurs a minimum charge of one language: you are charged for at least one language's dubbing when the project is created, before any output exists. This charge prepays the first language target — the first target you add, or the one queued via target_language, consumes it — and each additional language is charged separately.

Preparation can take minutes on a long source, so we recommend passing webhook_ids to be notified when the project turns ready or failed, rather than polling for it.

post/v1/dubbing/project

Request

  • Base URL
    https://api.elevenlabs.io (the document declares no server; this is the origin it was published from)
  • URL
    https://api.elevenlabs.io/v1/dubbing/project
  • Auth
    none declared

Headers

xi-api-keystring nullable

Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.

Request body multipart/form-data

filestring binary nullable

The source media file to dub: an audio or video file of at most 3 GiB. Provide this or source_url, not both.

source_urlstring nullable

Public HTTP(S) URL the source media is fetched from server-side, subject to the same size and format limits as an upload. Provide this or file, not both.

referencestring nullable

Optional free-form string (at most 500 characters) to identify the project on your end. Stored and echoed back verbatim; it does not affect the dub.

source_languagestring nullable

BCP-47 language tag of the source media; must be a language the transcription model supports. Any region or script subtag is ignored, since transcription is per-language. Omit to auto-detect.

keytermsstring[]

Key terms to bias transcription and translation toward (for example, product or brand names). At most 1,000 terms; each term at most 50 characters and 5 words; the characters <>{}[]\ are not allowed. Terms are trimmed and deduplicated. Repeat the field once per term, or pass a single JSON array.

webhook_idsstring[]

IDs of workspace webhooks to notify as this project progresses — the alternative to polling, and what we recommend. Each receives a dubbing_project_ready or dubbing_project_failed event for the project, and a dubbing_language_completed or dubbing_language_failed event for every language under it; dubbing_language_completed carries the output download URLs. At most 3 IDs, each already configured in your workspace — see Webhooks for how to create one and verify its signature. Repeat the field once per ID, or pass a single JSON array or comma-separated string. Delivery is best-effort and can repeat, so we recommend handling events idempotently.

target_languagestring nullable

Optional shortcut: also create a language target in this BCP-47 language, queued to start once the project is ready — equivalent to creating the project and then creating one language target. Must be one of the languages the dubbing model supports, and a region-qualified tag must be one of the supported dialects. This is the first language target, so it consumes the project's minimum charge rather than adding to it. Its ID is returned in language_ids.

transcriptstring binary nullable

Enterprise only. Optional JSON transcript to use instead of transcribing the source: a {"segments": [...]} document, at most 20,000 segments and 4 MiB. See Bring your own transcript for the segment fields and their constraints. source_language is required whenever a transcript is provided. If any segment carries a translation, target_language is required and every segment must carry one; those translations seed the target created via target_language, which then skips machine translation.

Response

Successful Response

project_idstring required

Unique identifier of the dubbing project.

status'queued' | 'preparing' | 'processing' | 'ready' | 'failed' required

Lifecycle status of the project: queued before the source is picked up, preparing while it is transcribed, ready once transcription is done and language targets can start, or failed. A project is never reported as processing — that value belongs to language targets.

referencestring nullable

The free-form string you supplied as reference when creating the project, or null if you supplied none.

source_languagestring nullable

BCP-47 language tag of the source media (null if auto-detected).

model_idstring nullable

Dubbing model every language target of this project is dubbed with. Fixed at create time and not selectable per language.

language_idsstring[]

Identifiers of the language targets under this project. Populated when a single project is fetched, and on create when target_language creates one. Always empty in list responses — list the project's language targets instead.

webhook_idsstring[]

IDs of the workspace webhooks notified as this project and its languages reach ready, completed, or failed.

revisioninteger required

Monotonic counter incremented whenever the source transcript is edited (segment add/edit/delete).

created_atstring date-time required

When the project was created.

updated_atstring date-time required

When the project was last updated.

Changes

  • 57d56f34628aRevision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

  • 1cae8adcc965Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status