---
title: "Create Dubbing Project"
method: POST
path: "/v1/dubbing/project"
tags: ["Dubbing"]
---

# Create Dubbing Project

`POST /v1/dubbing/project`

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. Creating a project does not dub anything — add a language target to it for each language you want, or pass `target_language` to queue the first one here.

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.

## Headers

- `xi-api-key` string, 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.

## Response `201`

Successful Response

- DubbingProjectResponse
  - `project_id` string, 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.
  - `reference` string, nullable — The free-form string you supplied as `reference` when creating the project, or null if you supplied none.
  - `source_language` string, nullable — BCP-47 language tag of the source media (null if auto-detected).
  - `model_id` string, nullable — Dubbing model every language target of this project is dubbed with. Fixed at create time and not selectable per language.
  - `media` DubbingSourceMediaInfo — Metadata about the project's source media.
    - `filename` string, nullable — Original filename of the uploaded source media (null for URL sources).
    - `duration_s` number, nullable — Duration of the source media, in seconds.
    - `has_video` boolean, nullable — Whether the source media contains a video stream.
    - `mime_type` string, nullable — MIME type of the uploaded source media (null for URL sources).
  - `language_ids` string[] — 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_ids` string[] — IDs of the workspace webhooks notified as this project and its languages reach `ready`, `completed`, or `failed`.
  - `revision` integer, required — Monotonic counter incremented whenever the source transcript is edited (segment add/edit/delete).
  - `error` DubbingError
    - `code` string, required — Stable identifier for the failure, safe to branch on. New codes are added over time, so we recommend treating an unrecognized value as `internal_error`.
    - `message` string, required — Human-readable description of the failure, for display. The wording may change at any time, so we recommend branching on `code` instead.
    - `retryable` boolean, required — Whether resubmitting the same input could succeed. A value of false means the failure describes the input or the account, so an identical retry will fail the same way.
  - `warnings` VoicesNotPermittedWarning[] — Non-fatal conditions raised while preparing the source, empty when there are none. Reflects the latest preparation. Conditions raised while dubbing a particular language are reported on that language instead.
    - `type` 'voices_not_permitted', required — Identifies this warning; branch on it to read the other fields.
    - `speaker_ids` string[], required — Speakers whose voices were not permitted for cloning. The dub used a replacement voice for each of them; all other speakers are unaffected.
    - `message` string, required — Human-readable description of the warning, for display. The wording may change at any time, so we recommend branching on `type` instead.
  - `created_at` string, date-time, required — When the project was created.
  - `updated_at` string, date-time, required — When the project was last updated.

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-07** `57d56f34628a` — 2 info
  - added the new optional request property `webhook_ids`
  - added the optional property `webhook_ids` to the response with the `201` status
- **2026-08-06** `1cae8adcc965` — 2 info
  - added the optional property `error` to the response with the `201` status
  - added the optional property `warnings` to the response with the `201` status
- **2026-08-05** `ebff0190de5c` — 1 breaking, 1 info
  - removed `subschema #1` from the `model_id` request property `anyOf` list
  - added `subschema #1, subschema #2` to the `model_id` request property `anyOf` list
- **2026-07-31** `72c54eba117e` — 1 info
  - added the new optional request property `transcript`

[Change history](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/changes/v1/dubbing/project/post.md)

---

[API](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation.md) · [All operations](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/elevenlabs/elevenlabs-api-documentation/revisions/630c650dda66/schema)