Try the API
No request is sent until you press the button.
Dubbing
/v1/dubbing. Check /v1/usage before paid work. Search for an existing project or connected YouTube video before creating one. Use the project's progress fields to decide whether to check again or wait for review. See the guides for project statuses and error responses.Create a project, review its transcript, then fine-tune each language.
Set processing_mode to automatic to dub without stopping, or keep creator_review to check the transcript first.
- 01CreateChoose languages, check credits, and start a project from YouTube or a file upload.List locales · YouTube videos · Usage · Create project · Complete upload
- 02Track and downloadFind projects, follow their progress, and download completed files.List projects · Get project · Download file
- 03Source transcriptRead and correct the source transcript before dubbing starts, then approve it.Read transcript · Edit transcript · Approve transcript · Human transcript review
- 04LanguagesAdd languages, read each translation, and fix or regenerate individual segments.Add languages · Read translation · Edit translation
Dubbing
Create
Choose languages, check credits, and start a project from YouTube or a file upload.
/v1/dubbing/localesList supported locales
Lists the source and target locales accepted by the Dubbing API. No authentication required.
Parameters
No request parameters.
curl "https://api.dittodub.com/v1/dubbing/locales"{
"data": [
{ "locale": "en_us", "display_name": "English - United States" },
{ "locale": "es_mx", "display_name": "Spanish - Mexico" },
{ "locale": "fr_fr", "display_name": "French - France" }
]
}/v1/dubbing/youtube/videosList connected YouTube videos
Lists recent or matching videos from YouTube channels connected to the workspace. If a video already has a DittoDub project, the response includes it.
Parameters
channel_idquerystringA connected channel ID. When omitted, DittoDub uses the workspace's primary channel.
queryquerystringSearch video titles or provide an exact YouTube video ID.
limitqueryintegerNumber of videos to return, from 1 to 50. Defaults to 20.
curl "https://api.dittodub.com/v1/dubbing/youtube/videos?query=launch&limit=20" \
--header "x-api-key: $DITTODUB_API_KEY"{
"data": {
"connection_required": false,
"channel": { "channel_id": "UC...", "title": "My channel" },
"items": [
{
"youtube_video_id": "VIDEO_ID",
"title": "Launch video",
"url": "https://www.youtube.com/watch?v=VIDEO_ID",
"duration_seconds": 487,
"matching_project": {
"project_id": "23fa9d79-cc42-4c82-90b8-2b7c78c57b31",
"state": "verified",
"target_locales": ["es_mx"]
}
}
]
}
}/v1/usageGet workspace usage
Returns total, reserved, and currently available workspace credits and billable seconds, plus how the workspace pays. Check this before starting paid work. billing.model is subscription, prepaid, or invoiced. Pay-as-you-go workspaces (prepaid, invoiced) also get their per-minute price and recent invoices, and on-demand (invoiced) workspaces get their credit limit, what they owe, and when the next invoice goes out. For on-demand workspaces, available credits are the unused part of the credit limit plus any plan credits. To raise the limit, request it from the Membership page in your DittoDub account; a pending request shows in billing.credit_limit_request.
Parameters
No request parameters.
curl "https://api.dittodub.com/v1/usage" \
--header "x-api-key: $DITTODUB_API_KEY"{
"data": {
"credits_per_second": 93,
"credits": {
"total": 930000,
"reserved": 93000,
"available": 837000
},
"billable_seconds": {
"total": 10000,
"reserved": 1000,
"available": 9000
},
"billing": {
"model": "invoiced",
"price_per_minute_usd": 2.62,
"suspended": false,
"credit_limit_seconds": 60000,
"owed_seconds": 18720,
"unbilled_seconds": 6720,
"invoiced_unpaid_seconds": 12000,
"payment_terms_days": 30,
"next_invoice_at": "2026-08-01T00:00:00.000Z",
"early_invoice_at_percent": 75,
"credit_limit_request": null,
"invoices": [
{
"period": "2026-07",
"status": "open",
"billable_seconds": 12000,
"amount_usd": 524,
"invoice_number": "DD-0042",
"invoice_url": "https://invoice.stripe.com/i/...",
"due_at": "2026-08-31T00:00:00.000Z",
"created_at": "2026-08-01T00:05:00.000Z"
}
]
},
"as_of": "2026-08-20T18:00:00.000Z"
}
}/v1/dubbing/projectsCreate a dubbing project
Creates a dubbing project from a YouTube URL or uploaded file and returns 201 with the project. For an upload source, the response also includes transfer: upload each part of the file to transfer.parts[].url, then call Complete upload.
Parameters
Idempotency-KeyheaderstringRequiredA unique key for this create request. Send the same key and body again to receive the original project.
namebodystringRequiredA human-readable project name, up to 100 characters.
external_idbodystringYour own stable identifier for later lookup.
source_localebodylocaleRequiredThe exact source locale returned by List locales.
target_localesbodylocale[]RequiredOne or more unique target locales.
max_billable_secondsbodyintegerRequiredIf validated billable duration exceeds this value, DittoDub stops before processing or charging.
processing_modebodyenumcreator_review (default) pauses after transcription so you can read, edit, and approve the source transcript. automatic starts dubbing as soon as transcription finishes.
sourcebodyobjectRequiredUse { type: youtube, url } or { type: upload, file_name, size_bytes }. Uploads accept mp4, mov, webm, mkv, m4v, avi, wmv, flv, or avchd files, and can include content_type.
curl "https://api.dittodub.com/v1/dubbing/projects" \
--request POST \
--header "x-api-key: $DITTODUB_API_KEY" \
--header "Idempotency-Key: launch-video-1042" \
--header "Content-Type: application/json" \
--data '{
"name": "Launch video",
"external_id": "video-1042",
"source_locale": "en_us",
"target_locales": ["es_mx", "fr_fr"],
"max_billable_seconds": 1800,
"processing_mode": "creator_review",
"source": {
"type": "youtube",
"url": "https://www.youtube.com/watch?v=VIDEO_ID"
}
}'{
"data": {
"id": "23fa9d79-cc42-4c82-90b8-2b7c78c57b31",
"external_id": "video-1042",
"name": "Launch video",
"status": "validating",
"source_locale": "en_us",
"target_locales": ["es_mx", "fr_fr"],
"usage": {
"max_billable_seconds": 1800,
"billable_seconds": null,
"charged_seconds": 0,
"state": "pending_validation"
},
"languages": []
}
}/v1/dubbing/projects/{project_id}/upload/completeComplete an upload
Finishes an upload project. Split the file into transfer.part_size_bytes chunks, send each chunk with PUT to its transfer.parts[].url, and keep the ETag header from each response. Then send every part here to start source validation.
Parameters
project_idpathstringRequiredThe upload project returned by Create project.
partsbodyarrayRequiredEvery part_number from transfer.parts with the ETag returned by its PUT request, in ascending order. All transfer.total_parts parts are required.
curl "https://api.dittodub.com/v1/dubbing/projects/PROJECT_ID/upload/complete" \
--request POST \
--header "x-api-key: $DITTODUB_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"parts": [
{ "part_number": 1, "etag": "ETAG_FROM_UPLOAD_RESPONSE" }
]
}'{
"data": {
"id": "23fa9d79-cc42-4c82-90b8-2b7c78c57b31",
"status": "validating",
"source": { "type": "upload", "file_name": "launch-video.mp4" }
}
}Dubbing
Track and download
Find projects, follow their progress, and download completed files.
/v1/dubbing/projectsList dubbing projects
Lists projects with cursor pagination. Filter by external ID or YouTube video ID to find a known project.
Parameters
limitqueryintegerNumber of projects to return, from 1 to 50. Defaults to 20.
cursorquerystringThe opaque next_cursor from the previous response.
external_idquerystringReturn projects with your external identifier.
youtube_video_idquerystringReturn projects created for this YouTube video ID.
queryquerystringSearch project names, external IDs, or an exact YouTube video ID.
curl "https://api.dittodub.com/v1/dubbing/projects?limit=20" \
--header "x-api-key: $DITTODUB_API_KEY"{
"data": [
{
"id": "23fa9d79-cc42-4c82-90b8-2b7c78c57b31",
"name": "Launch video",
"status": "processing",
"progress": {
"phase": "dubbing",
"waiting_on": "dittodub",
"can_advance_without_user": true,
"poll_after_seconds": 60,
"message": "DittoDub is processing one or more target languages."
},
"target_locales": ["es_mx", "fr_fr"]
}
],
"page": {
"has_more": true,
"next_cursor": "eyJ2IjoxLCJjcmVhdGVkX2F0IjoiLi4uIn0"
}
}/v1/dubbing/projects/{project_id}Get a dubbing project
Returns project status and usage, source transcript review status, progress for each language, publishing metadata, and completed files. Upload projects that are still awaiting their file also include transfer with fresh upload URLs.
Parameters
project_idpathstringRequiredThe project ID returned when the project was created.
include_transferquerybooleanDefaults to true. Set false to skip refreshing upload URLs for a project that is still awaiting its file.
curl "https://api.dittodub.com/v1/dubbing/projects/PROJECT_ID" \
--header "x-api-key: $DITTODUB_API_KEY"{
"data": {
"id": "23fa9d79-cc42-4c82-90b8-2b7c78c57b31",
"status": "completed",
"usage": {
"max_billable_seconds": 1800,
"billable_seconds": 487,
"charged_seconds": 974,
"state": "charged"
},
"languages": [
{
"locale": "es_mx",
"status": "completed",
"deliverables": [
{ "type": "audio", "format": "mp3", "download_url": "https://api.dittodub.com/v1/dubbing/projects/PROJECT_ID/download?locale=es_mx&type=audio" }
]
}
]
}
}/v1/dubbing/projects/{project_id}/downloadDownload a completed file
Returns a completed file through a stable authenticated URL. Audio and thumbnails redirect to short-lived storage URLs. DittoDub returns subtitle files directly.
Parameters
project_idpathstringRequiredThe project that owns the deliverable.
localequerylocaleRequiredThe completed target locale.
typequeryenumRequiredaudio, subtitles, or thumbnail.
formatqueryenumFor subtitles only: srt or vtt. Defaults to vtt.
curl --location \
"https://api.dittodub.com/v1/dubbing/projects/PROJECT_ID/download?locale=es_mx&type=subtitles&format=vtt" \
--header "x-api-key: $DITTODUB_API_KEY" \
--output launch-video.es-MX.vttWEBVTT
00:00:00.000 --> 00:00:02.480
Bienvenidos a nuestro video de lanzamiento.Dubbing
Source transcript
Read and correct the source transcript before dubbing starts, then approve it.
/v1/dubbing/projects/{project_id}/transcriptRead the source transcript
Returns the source transcript as timed segments and the speakers found in it. editable is true while the project status is awaiting_creator_review, which is where creator_review projects wait after transcription.
Parameters
project_idpathstringRequiredThe project ID returned when the project was created.
curl "https://api.dittodub.com/v1/dubbing/projects/PROJECT_ID/transcript" \
--header "x-api-key: $DITTODUB_API_KEY"{
"data": {
"project_id": "PROJECT_ID",
"locale": "en_us",
"editable": true,
"speakers": [
{ "id": "speaker_1", "name": "Speaker 1" },
{ "id": "speaker_2", "name": "Speaker 2" }
],
"segments": [
{
"id": "SEGMENT_ID",
"start": 0,
"end": 2.48,
"text": "Welcome to our launch video.",
"speaker": { "id": "speaker_1", "name": "Speaker 1" }
}
]
}
}/v1/dubbing/projects/{project_id}/transcriptEdit the source transcript
Changes the text or speaker of individual segments while the project is awaiting_creator_review. Segments you leave out stay the same. Timing does not change. Edits are free and return the updated transcript.
Parameters
project_idpathstringRequiredThe project whose source transcript you are editing.
segmentsbodyarrayRequiredUp to 1,000 edits. Each has the segment id plus text, speaker_id, or both. speaker_id must come from the transcript's speakers list.
curl "https://api.dittodub.com/v1/dubbing/projects/PROJECT_ID/transcript" \
--request PATCH \
--header "x-api-key: $DITTODUB_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"segments": [
{ "id": "SEGMENT_ID", "text": "Welcome to our product launch." },
{ "id": "OTHER_SEGMENT_ID", "speaker_id": "speaker_2" }
]
}'{
"data": {
"project_id": "PROJECT_ID",
"editable": true,
"segments": [
{
"id": "SEGMENT_ID",
"start": 0,
"end": 2.48,
"text": "Welcome to our product launch.",
"speaker": { "id": "speaker_1", "name": "Speaker 1" }
}
]
}
}/v1/dubbing/projects/{project_id}/transcript/approveApprove the source transcript
Checks the saved transcript and starts translation and dubbing for every target language. Each segment needs text and no more than about 50 characters per second of speech. If a segment fails, the error names it so you can fix it and approve again. Projects whose languages are paid at approval must be approved in DittoDub so the charge can be reviewed.
Parameters
project_idpathstringRequiredA project whose status is awaiting_creator_review.
curl "https://api.dittodub.com/v1/dubbing/projects/PROJECT_ID/transcript/approve" \
--request POST \
--header "x-api-key: $DITTODUB_API_KEY"{
"data": {
"id": "PROJECT_ID",
"status": "queued",
"progress": {
"phase": "queued_for_dubbing",
"waiting_on": "dittodub",
"can_advance_without_user": true,
"poll_after_seconds": 60,
"message": "Target languages are queued for dubbing."
}
}
}/v1/dubbing/projects/{project_id}/transcript-reviewSubmit the source transcript for human review
Returns an exact quote or submits the English or Arabic source transcript to Ditto Verified. It never sends a translated transcript. Preview the quote first, then submit with the approved spend ceiling.
Parameters
project_idpathstringRequiredThe project whose English or Arabic source transcript needs review.
max_billable_secondsbodyintegerRequiredLimits billable seconds for the review. If the project duration rounds above it, DittoDub does not submit or charge.
preview_onlybodybooleanDefaults to true. Set false only after accepting the returned quote.
Idempotency-KeyheaderstringRequired when preview_only is false. Reuse the same key when retrying that accepted request.
curl "https://api.dittodub.com/v1/dubbing/projects/PROJECT_ID/transcript-review" \
--request POST \
--header "x-api-key: $DITTODUB_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"max_billable_seconds": 1800,
"preview_only": true
}'{
"data": {
"project": {
"id": "23fa9d79-cc42-4c82-90b8-2b7c78c57b31",
"transcript_review": {
"requested": false,
"status": "not_requested"
}
},
"review": {
"preview_only": true,
"already_requested": false,
"billable_seconds": 487,
"credits": 45291,
"max_billable_seconds": 1800,
"within_limit": true,
"charged_now_seconds": 0
},
"idempotent_replay": false
}
}Dubbing
Languages
Add languages, read each translation, and fix or regenerate individual segments.
/v1/dubbing/projects/{project_id}/languagesAdd languages to a project
Returns an exact quote for new target languages. The default preview does not charge or change the project. After approval, set preview_only to false to add them.
Parameters
project_idpathstringRequiredThe existing project that should receive new languages.
target_localesbodylocale[]RequiredExact locales returned by List locales.
max_billable_secondsbodyintegerRequiredLimits billable seconds for the full request. If the quote exceeds it, DittoDub does not charge or add languages.
preview_onlybodybooleanDefaults to true. Set false only after accepting the returned quote.
Idempotency-KeyheaderstringRequired when preview_only is false. Reuse the same key when retrying that accepted request.
curl "https://api.dittodub.com/v1/dubbing/projects/PROJECT_ID/languages" \
--request POST \
--header "x-api-key: $DITTODUB_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"target_locales": ["de_de", "ja_jp"],
"max_billable_seconds": 1800,
"preview_only": true
}'{
"data": {
"addition": {
"preview_only": true,
"existing_locales": [],
"new_locales": ["de_de", "ja_jp"],
"billable_seconds": 974,
"credits": 90582,
"max_billable_seconds": 1800,
"within_limit": true
},
"idempotent_replay": false
}
}/v1/dubbing/projects/{project_id}/languages/{locale}/transcriptRead a translation
Returns the translated segments for one target language. Each segment includes its source_text. editable is true once the language has finished processing.
Parameters
project_idpathstringRequiredThe project that owns the language.
localepathlocaleRequiredA target locale on the project, such as es_mx.
curl "https://api.dittodub.com/v1/dubbing/projects/PROJECT_ID/languages/es_mx/transcript" \
--header "x-api-key: $DITTODUB_API_KEY"{
"data": {
"project_id": "PROJECT_ID",
"locale": "es_mx",
"status": "completed",
"editable": true,
"segments": [
{
"id": "SEGMENT_ID",
"start": 0,
"end": 2.48,
"text": "Bienvenidos a nuestro video de lanzamiento.",
"source_text": "Welcome to our launch video.",
"speaker": { "id": "VOICE_ID", "name": "Speaker 1" }
}
]
}
}/v1/dubbing/projects/{project_id}/languages/{locale}/transcriptEdit or regenerate segments
Changes the translated text of individual segments, or asks DittoDub to re-voice them with their current text. The request returns right away and the language is re-rendered in the background: its status goes to queued, then processing, then completed when the new audio and video are ready to download. The language accepts new edits once it completes again, so send all changes for a language in one request. Changed segments use billable seconds equal to their combined length, rounded up to the next second. Unchanged text is skipped and not charged.
Parameters
project_idpathstringRequiredThe project that owns the language.
localepathlocaleRequiredA completed target locale on the project.
segmentsbodyarrayRequiredUp to 1,000 items. Each has a segment id plus new text, regenerate: true, or both.
curl "https://api.dittodub.com/v1/dubbing/projects/PROJECT_ID/languages/es_mx/transcript" \
--request PATCH \
--header "x-api-key: $DITTODUB_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"segments": [
{ "id": "SEGMENT_ID", "text": "Bienvenidos a nuestro lanzamiento." },
{ "id": "OTHER_SEGMENT_ID", "regenerate": true }
]
}'{
"data": {
"project": {
"id": "PROJECT_ID",
"status": "processing",
"languages": [{ "locale": "es_mx", "status": "queued" }]
},
"updated_segment_ids": ["SEGMENT_ID", "OTHER_SEGMENT_ID"]
}
}