Video dubbing API reference

Use the REST API to create projects, track each target language, and download completed files.

Base URLhttps://api.dittodub.com

Try the API

Send a request from this page. Your API key remains in this browser tab and is not saved or included when you copy the agent setup. Start with List locales, which does not require authentication.

No request is sent until you press the button.

Dubbing

All dubbing routes start with /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.

Dubbing

Create

Choose languages, check credits, and start a project from YouTube or a file upload.

GET/v1/dubbing/locales

List supported locales

Lists the source and target locales accepted by the Dubbing API. No authentication required.

Parameters

No request parameters.

Request
curl "https://api.dittodub.com/v1/dubbing/locales"
Example response
{
  "data": [
    { "locale": "en_us", "display_name": "English - United States" },
    { "locale": "es_mx", "display_name": "Spanish - Mexico" },
    { "locale": "fr_fr", "display_name": "French - France" }
  ]
}
GET/v1/dubbing/youtube/videos

List 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_idquerystring

A connected channel ID. When omitted, DittoDub uses the workspace's primary channel.

queryquerystring

Search video titles or provide an exact YouTube video ID.

limitqueryinteger

Number of videos to return, from 1 to 50. Defaults to 20.

Request
curl "https://api.dittodub.com/v1/dubbing/youtube/videos?query=launch&limit=20" \
  --header "x-api-key: $DITTODUB_API_KEY"
Example response
{
  "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"]
        }
      }
    ]
  }
}
GET/v1/usage

Get 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.

Request
curl "https://api.dittodub.com/v1/usage" \
  --header "x-api-key: $DITTODUB_API_KEY"
Example response
{
  "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"
  }
}
POST/v1/dubbing/projects

Create 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-KeyheaderstringRequired

A unique key for this create request. Send the same key and body again to receive the original project.

namebodystringRequired

A human-readable project name, up to 100 characters.

external_idbodystring

Your own stable identifier for later lookup.

source_localebodylocaleRequired

The exact source locale returned by List locales.

target_localesbodylocale[]Required

One or more unique target locales.

max_billable_secondsbodyintegerRequired

If validated billable duration exceeds this value, DittoDub stops before processing or charging.

processing_modebodyenum

creator_review (default) pauses after transcription so you can read, edit, and approve the source transcript. automatic starts dubbing as soon as transcription finishes.

sourcebodyobjectRequired

Use { 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.

Request
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"
    }
  }'
Example response
{
  "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": []
  }
}
POST/v1/dubbing/projects/{project_id}/upload/complete

Complete 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_idpathstringRequired

The upload project returned by Create project.

partsbodyarrayRequired

Every part_number from transfer.parts with the ETag returned by its PUT request, in ascending order. All transfer.total_parts parts are required.

Request
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" }
    ]
  }'
Example 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.

GET/v1/dubbing/projects

List dubbing projects

Lists projects with cursor pagination. Filter by external ID or YouTube video ID to find a known project.

Parameters

limitqueryinteger

Number of projects to return, from 1 to 50. Defaults to 20.

cursorquerystring

The opaque next_cursor from the previous response.

external_idquerystring

Return projects with your external identifier.

youtube_video_idquerystring

Return projects created for this YouTube video ID.

queryquerystring

Search project names, external IDs, or an exact YouTube video ID.

Request
curl "https://api.dittodub.com/v1/dubbing/projects?limit=20" \
  --header "x-api-key: $DITTODUB_API_KEY"
Example response
{
  "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"
  }
}
GET/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_idpathstringRequired

The project ID returned when the project was created.

include_transferqueryboolean

Defaults to true. Set false to skip refreshing upload URLs for a project that is still awaiting its file.

Request
curl "https://api.dittodub.com/v1/dubbing/projects/PROJECT_ID" \
  --header "x-api-key: $DITTODUB_API_KEY"
Example response
{
  "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" }
        ]
      }
    ]
  }
}
GET/v1/dubbing/projects/{project_id}/download

Download 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_idpathstringRequired

The project that owns the deliverable.

localequerylocaleRequired

The completed target locale.

typequeryenumRequired

audio, subtitles, or thumbnail.

formatqueryenum

For subtitles only: srt or vtt. Defaults to vtt.

Request
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.vtt
Example response
WEBVTT

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.

GET/v1/dubbing/projects/{project_id}/transcript

Read 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_idpathstringRequired

The project ID returned when the project was created.

Request
curl "https://api.dittodub.com/v1/dubbing/projects/PROJECT_ID/transcript" \
  --header "x-api-key: $DITTODUB_API_KEY"
Example response
{
  "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" }
      }
    ]
  }
}
PATCH/v1/dubbing/projects/{project_id}/transcript

Edit 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_idpathstringRequired

The project whose source transcript you are editing.

segmentsbodyarrayRequired

Up 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.

Request
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" }
    ]
  }'
Example response
{
  "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" }
      }
    ]
  }
}
POST/v1/dubbing/projects/{project_id}/transcript/approve

Approve 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_idpathstringRequired

A project whose status is awaiting_creator_review.

Request
curl "https://api.dittodub.com/v1/dubbing/projects/PROJECT_ID/transcript/approve" \
  --request POST \
  --header "x-api-key: $DITTODUB_API_KEY"
Example response
{
  "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."
    }
  }
}
POST/v1/dubbing/projects/{project_id}/transcript-review

Submit 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_idpathstringRequired

The project whose English or Arabic source transcript needs review.

max_billable_secondsbodyintegerRequired

Limits billable seconds for the review. If the project duration rounds above it, DittoDub does not submit or charge.

preview_onlybodyboolean

Defaults to true. Set false only after accepting the returned quote.

Idempotency-Keyheaderstring

Required when preview_only is false. Reuse the same key when retrying that accepted request.

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
  }'
Example response
{
  "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.

POST/v1/dubbing/projects/{project_id}/languages

Add 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_idpathstringRequired

The existing project that should receive new languages.

target_localesbodylocale[]Required

Exact locales returned by List locales.

max_billable_secondsbodyintegerRequired

Limits billable seconds for the full request. If the quote exceeds it, DittoDub does not charge or add languages.

preview_onlybodyboolean

Defaults to true. Set false only after accepting the returned quote.

Idempotency-Keyheaderstring

Required when preview_only is false. Reuse the same key when retrying that accepted request.

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
  }'
Example response
{
  "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
  }
}
GET/v1/dubbing/projects/{project_id}/languages/{locale}/transcript

Read 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_idpathstringRequired

The project that owns the language.

localepathlocaleRequired

A target locale on the project, such as es_mx.

Request
curl "https://api.dittodub.com/v1/dubbing/projects/PROJECT_ID/languages/es_mx/transcript" \
  --header "x-api-key: $DITTODUB_API_KEY"
Example response
{
  "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" }
      }
    ]
  }
}
PATCH/v1/dubbing/projects/{project_id}/languages/{locale}/transcript

Edit 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_idpathstringRequired

The project that owns the language.

localepathlocaleRequired

A completed target locale on the project.

segmentsbodyarrayRequired

Up to 1,000 items. Each has a segment id plus new text, regenerate: true, or both.

Request
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 }
    ]
  }'
Example response
{
  "data": {
    "project": {
      "id": "PROJECT_ID",
      "status": "processing",
      "languages": [{ "locale": "es_mx", "status": "queued" }]
    },
    "updated_segment_ids": ["SEGMENT_ID", "OTHER_SEGMENT_ID"]
  }
}