Workflow guide

Creating a dub

Start from a single source video, create a dubbing project in one or more languages, wait for processing to finish, and then download the final dubbed audio or subtitles.

  1. Step 1. Get an API key and choose what to dub

    Go to dittodub.com/account/api and create an API key. Keep that key handy for the API console on this page or export it as an API_KEY environment variable for your scripts (the examples below already use the production host). Decide what you want to dub: either a YouTube video (using youtube_video_id from the URL) or a direct media file you host yourself (using source_url to a downloadable HTTPS video or audio file).

    Shell setup
    ```bash
# 1) Get an API key and set your environment
#    (create a key at https://dittodub.com/account/api)
export API_KEY="YOUR_API_KEY"
# Requests below target https://babelfish.dittodub.com
```

  2. Step 2. Create the dubbing project

    Call POST /api/dubbing to create a new project. Always send a languages array (for example ["es", "fr"]) and then choose one of two input options: either youtube_video_id for a YouTube video, or source_url for a direct media URL you control. When using source_url, Ditto automatically probes the file with ffprobe to determine its duration, and you can also pass optional fields like source_title, source_description, source_thumbnail, source_tags, source_language, plus flags such as ditto_transcript_verified and automatic to let Ditto handle more of the setup for you.

    Create project (curl)
    ```bash
# Create a dub from a YouTube video
curl -X POST "https://babelfish.dittodub.com/api/dubbing" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"languages":["es"],"youtube_video_id":"dQw4w9WgXcQ","automatic":true}'

# Or: create a dub from a direct media URL you control
curl -X POST "https://babelfish.dittodub.com/api/dubbing" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"languages":["es","fr"],"source_url":"https://example.com/video.mp4"}'
```

  3. Step 3. Check when the dub is ready

    The create call returns a project_id. Use GET /api/dubbing with that project_id to poll the project and check its state. In your own scripts, you typically loop every few seconds until the project comes back with a state of "verified", which means the dubbing work is complete and ready to download.

    Check project status
    ```bash
# Poll until state is "verified"
curl -X GET "https://babelfish.dittodub.com/api/dubbing?project_id=YOUR_PROJECT_ID" \
  -H "x-api-key: $API_KEY"
```

  4. Step 4. Download the completed dub

    Once the project is verified, call GET /api/dubbing/download with the project_id, the language code you want (for example "es"), and a type such as "audio" or "subtitles". For subtitles you can also choose a format like "srt" or "vtt". The response contains a URL you can use to download the finished file and store or serve it from your own application.

    Download dub
    ```bash
# Download dubbed audio
curl -L "https://babelfish.dittodub.com/api/dubbing/download?type=audio&project_id=YOUR_PROJECT_ID&language=es" \
  -H "x-api-key: $API_KEY"

# Download subtitles (VTT or SRT)
curl -L "https://babelfish.dittodub.com/api/dubbing/download?type=subtitles&format=vtt&project_id=YOUR_PROJECT_ID" \
  -H "x-api-key: $API_KEY"
```