Quickstart

By the end of this page you will have uploaded a video, had it dubbed into Spanish with voices cloned from its own speakers, and downloaded an MP4 that carries both the Spanish dub and the original audio.

Get access

VOD Express comes with every SyncWords Live account: if your organization uses Live, it can use VOD Express too, with the same API key pair (a public key and a secret). Without one, ask your SyncWords contact, or support@syncwords.com, for an account.

You need

The key pair, and about 15 minutes: processing a file takes 4 to 10 minutes even for a short clip, most of it spent preparing the processing for the file.
A short video with speech. Use ours, a 35-second English dialogue (1 MB): sample-en.mp4; or any MP4 of a minute or two.
curl -s -o episode.mp4 https://docs.syncwords.com/vod-express/samples/sample-en.mp4
One of:
- curl and jq
- Python 3.9+ with requests (pip install requests)
- Node.js 20+

Each step’s snippet builds on the ones before it: run the curl snippets in one shell, and put the Python or Node.js snippets one after another in one file (quickstart.py, or quickstart.mjs for its top-level await). The base URL is read from SW_VOD_API when set, and is that of Environments otherwise.

Get a token

Exchange the key pair for a bearer token, and set up a small helper for the calls that follow:

API=${SW_VOD_API:-https://api-vod-express.syncwords.com/v1}

TOKEN=$(curl -s "$API/token/create" \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -d '{"username": "YOUR_PUBLIC_KEY", "password": "YOUR_SECRET_KEY"}' | jq -r .access_token)
AUTH="Authorization: Bearer $TOKEN"

import os
import time

import requests

API = os.environ.get("SW_VOD_API", "https://api-vod-express.syncwords.com/v1")

response = requests.post(
    API + "/token/create",
    json={"username": "YOUR_PUBLIC_KEY", "password": "YOUR_SECRET_KEY"},
    headers={"Accept": "application/json"},
)
response.raise_for_status()
token = response.json()["access_token"]


def api(method, path, body=None):
    response = requests.request(
        method, API + path, json=body,
        headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
    )
    if not response.ok:
        raise RuntimeError(f"{method} {path}: {response.status_code} {response.text}")
    return response.json()["data"]

import { readFile, stat, writeFile } from 'node:fs/promises';

const API = process.env.SW_VOD_API ?? 'https://api-vod-express.syncwords.com/v1';

const response = await fetch(`${API}/token/create`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
  body: JSON.stringify({ username: 'YOUR_PUBLIC_KEY', password: 'YOUR_SECRET_KEY' }),
});
if (!response.ok) throw new Error(`token: ${response.status} ${await response.text()}`);
const { access_token: token } = await response.json();

async function api(method, path, body) {
  const response = await fetch(API + path, {
    method,
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: 'application/json',
      ...(body ? { 'Content-Type': 'application/json' } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await response.json();
  if (!response.ok) throw new Error(`${method} ${path}: ${response.status} ${JSON.stringify(json)}`);
  return json.data;
}

A token lasts 30 minutes. When a call answers 401, get a new one the same way. More on tokens.

Check your access

curl -s -H "$AUTH" $API/whoami | jq .data.vodExpress

print(api("GET", "/whoami")["vodExpress"])

console.log((await api('GET', '/whoami')).vodExpress);

{ "enabled": true, "defaultBuildVersion": "0.9.0-alpha1-2026-10-05T14-57Z-bf4a93", "hasAwsAccess": false, "canManageAccount": true }

enabled: false means VOD Express is not available to the account, for instance because its access was revoked or its trial ended: every other call then answers 403, and its message says why. Ask support.

Create a project

A project holds the processing instructions. This one reads the files put into its input folder (S3FolderSource), transcribes English, translates into Spanish with Gemini, dubs with Deepdub cloning each speaker’s voice (voice: auto), and writes an MP4 per input into its output folder (S3FolderOutput), with the input’s own audio as the first track and the Spanish dub as the second:

PROJECT=$(curl -s -X POST $API/projects -H "$AUTH" -H 'Content-Type: application/json' -d '{
  "name": "My first dub",
  "config": {
    "sourceMedia": { "@type": "S3FolderSource" },
    "transcription": { "@type": "Speechmatics", "language": "en" },
    "translations": [
      {
        "language": "es",
        "engine": { "@type": "Gemini" },
        "ttsOptions": { "provider": { "@type": "Deepdub", "voice": "auto" } }
      }
    ],
    "outputs": [
      {
        "@type": "S3FolderOutput",
        "items": [
          {
            "@type": "VideoFile",
            "ext": "mp4",
            "nameTemplate": "${name}.es.${ext}",
            "useOriginalTracks": true,
            "dubTracks": [{ "language": "es", "title": "Español" }]
          }
        ]
      }
    ]
  }
}' | jq -r .data.id)
echo $PROJECT

project = api("POST", "/projects", {
    "name": "My first dub",
    "config": {
        "sourceMedia": {"@type": "S3FolderSource"},
        "transcription": {"@type": "Speechmatics", "language": "en"},
        "translations": [
            {
                "language": "es",
                "engine": {"@type": "Gemini"},
                "ttsOptions": {"provider": {"@type": "Deepdub", "voice": "auto"}},
            }
        ],
        "outputs": [
            {
                "@type": "S3FolderOutput",
                "items": [
                    {
                        "@type": "VideoFile",
                        "ext": "mp4",
                        "nameTemplate": "${name}.es.${ext}",
                        "useOriginalTracks": True,
                        "dubTracks": [{"language": "es", "title": "Español"}],
                    }
                ],
            }
        ],
    },
})["id"]
print(project)

const project = (
  await api('POST', '/projects', {
    name: 'My first dub',
    config: {
      sourceMedia: { '@type': 'S3FolderSource' },
      transcription: { '@type': 'Speechmatics', language: 'en' },
      translations: [
        {
          language: 'es',
          engine: { '@type': 'Gemini' },
          ttsOptions: { provider: { '@type': 'Deepdub', voice: 'auto' } },
        },
      ],
      outputs: [
        {
          '@type': 'S3FolderOutput',
          items: [
            {
              '@type': 'VideoFile',
              ext: 'mp4',
              nameTemplate: '${name}.es.${ext}',
              useOriginalTracks: true,
              dubTracks: [{ language: 'es', title: 'Español' }],
            },
          ],
        },
      ],
    },
  })
).id;
console.log(project);

${name} and ${ext} in nameTemplate are the API’s placeholders, filled per input file, so the Node.js snippet keeps them in single quotes rather than a template literal.The project starts right away ("status": "running") and waits for files. If the config has a mistake, the answer is a 422 listing every problem by its place in the config. See Errors.

Upload a video

Ask the API for an upload URL, then PUT the file to it. The bytes go straight to storage, and the file is in the project as soon as the PUT completes:

FILE=episode.mp4
URL=$(curl -s -X POST $API/projects/$PROJECT/uploads -H "$AUTH" -H 'Content-Type: application/json' \
  -d "{\"name\": \"$FILE\", \"size\": $(wc -c < "$FILE" | tr -d ' ')}" | jq -r .data.url)
curl -T "$FILE" "$URL"

file = "episode.mp4"
url = api("POST", f"/projects/{project}/uploads", {"name": file, "size": os.path.getsize(file)})["url"]
with open(file, "rb") as handle:
    requests.put(url, data=handle).raise_for_status()

const file = 'episode.mp4';
const { url } = await api('POST', `/projects/${project}/uploads`, { name: file, size: (await stat(file)).size });
const put = await fetch(url, { method: 'PUT', body: await readFile(file) });
if (!put.ok) throw new Error(`upload: S3 answered ${put.status}`);

Storage answers 200 with an empty body. The URL works for a file of up to 5 GB; a larger file, or an upload you want to resume after an interruption, goes in parts.

Moving many files, or files from a pipeline? Use the AWS CLI with the role the API vends for your account: aws s3 sync ./season-1 s3://…/input/season-1/. See Upload with the AWS CLI.

Wait for it

curl -s -H "$AUTH" $API/projects/$PROJECT/files | jq '.data[] | {name, status, outputs}'

for f in api("GET", f"/projects/{project}/files"):
    print(f["name"], f["status"], f["outputs"])

for (const f of await api('GET', `/projects/${project}/files`)) {
  console.log(f.name, f.status, f.outputs);
}

{
  "name": "episode.mp4",
  "status": "pending",
  "outputs": [{ "path": "episode.es.mp4", "available": false, "size": null }]
}

A file goes from pending to processing to done (or failed). This is the 4 to 10 minutes of waiting, and most of it reads pending: processing is only the last step. To wait in a loop:

until curl -s -H "$AUTH" $API/projects/$PROJECT/files \
  | jq -e 'all(.data[]; .status == "done" or .status == "failed")' > /dev/null; do sleep 30; done

while not all(f["status"] in ("done", "failed") for f in api("GET", f"/projects/{project}/files")):
    time.sleep(30)

while (!(await api('GET', `/projects/${project}/files`)).every((f) => ['done', 'failed'].includes(f.status))) {
  await new Promise((resolve) => setTimeout(resolve, 30_000));
}

A token lasts 30 minutes, so a long wait may need a new one: the loop in Monitoring renews it on 401.

Download the dub

URL=$(curl -s -H "$AUTH" "$API/projects/$PROJECT/outputs/download?path=episode.es.mp4" | jq -r .data.url)
curl -s -o episode.es.mp4 "$URL"

url = api("GET", f"/projects/{project}/outputs/download?path=episode.es.mp4")["url"]
with requests.get(url, stream=True) as response, open("episode.es.mp4", "wb") as out:
    response.raise_for_status()
    for chunk in response.iter_content(1 << 20):
        out.write(chunk)

const { url } = await api('GET', `/projects/${project}/outputs/download?path=episode.es.mp4`);
const download = await fetch(url);
if (!download.ok) throw new Error(`download: S3 answered ${download.status}`);
await writeFile('episode.es.mp4', Buffer.from(await download.arrayBuffer()));

The link is a presigned S3 URL, valid for an hour. Open episode.es.mp4 in any player: it opens on the original audio, and the player’s audio menu switches to the Spanish dub.

What happened

The project launched a processing service when you created it. It picked up episode.mp4 from the project’s input folder, transcribed it, translated each sentence, cloned each speaker’s voice for the Spanish lines, and mixed the new voices over the original background (the voices of the original are removed, because originalAudioSplitting is on by default).
The service stops itself 30 minutes after it has nothing left to do, and starts again on its own within a minute of your next upload (startOnNewFiles, on by default). See Auto-stop.
Every further file you upload is processed with the same configuration.

Next steps

More languages, more outputs

Several dubs in one video, per-language files, subtitles beside them.

Pick voices

A safe first voice for each provider, and how to try one before a season.

Automate it

A complete Python or Node.js client: token renewal, a folder of files, every output.

Upload a whole season

The AWS CLI, subfolders, and collecting every output.

Get started

Concepts

Configure a project

Upload media

Examples

Going to production

Help

Get access

You need

What happened

Next steps

More languages, more outputs

Pick voices

Automate it

Upload a whole season

​Get access

​You need

​What happened

​Next steps

More languages, more outputs

Pick voices

Automate it

Upload a whole season

Get access

You need

What happened

Next steps