Create a project

curl --request POST \
  --url https://api-vod-express.syncwords.com/v1/projects \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Fishing Channel S01",
  "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": "Spanish"
              }
            ]
          }
        ]
      }
    ]
  }
}
'

import requests

url = "https://api-vod-express.syncwords.com/v1/projects"

payload = {
    "name": "Fishing Channel S01",
    "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": "Spanish"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Fishing Channel S01',
    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: 'Spanish'}]
            }
          ]
        }
      ]
    }
  })
};

fetch('https://api-vod-express.syncwords.com/v1/projects', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "id": "01m3k8jnrdw509457nhz7w81bq",
    "name": "Fishing Channel S01",
    "description": null,
    "buildVersion": "0.9.0-alpha1-2026-10-20T14-10Z-3f05aa",
    "status": "running",
    "files": {
      "total": 3,
      "pending": 1,
      "processing": 0,
      "done": 1,
      "failed": 1,
      "countedAt": "2026-09-28T06:15:00.000Z"
    },
    "startOnNewFiles": true,
    "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": "Spanish"
                }
              ]
            }
          ]
        }
      ]
    },
    "storage": {
      "connection": null,
      "path": "s3://sw-vod-express/projects/141/01m3k8jnrdw509457nhz7w81bq/",
      "inputPath": "s3://sw-vod-express/projects/141/01m3k8jnrdw509457nhz7w81bq/input/",
      "outputPath": "s3://sw-vod-express/projects/141/01m3k8jnrdw509457nhz7w81bq/output/",
      "inputPrefix": null,
      "outputPrefix": null
    },
    "meta": {
      "createdAt": "2026-09-28T05:42:35.534Z",
      "updatedAt": "2026-09-28T05:42:35.534Z",
      "createdBy": {
        "accountId": 141,
        "accountName": "Acme Media",
        "userId": null,
        "userEmail": null,
        "userFullName": null
      },
      "configLocked": false,
      "messages": []
    }
  }
}

{
  "message": "<string>",
  "code": "bad_request",
  "errors": {}
}

{
  "message": "Unauthenticated.",
  "code": "unauthenticated"
}

{
  "message": [
    "VOD Express is not enabled for your account."
  ],
  "code": "vod_express_not_enabled"
}

{
  "message": [
    "A request with this Idempotency-Key is still in progress. Retry it shortly."
  ],
  "code": "idempotency_in_progress"
}

{
  "message": [
    "The request body is too large."
  ],
  "code": "payload_too_large"
}

{
  "message": [
    "Send the body as JSON (Content-Type: application/json) or YAML (Content-Type: application/yaml)."
  ],
  "code": "unsupported_media_type"
}

{
  "code": "validation_failed",
  "message": "No translation has ttsOptions, so there is no dub to add: use useOriginalTracks for the input’s audio. (and 2 more errors)",
  "errors": {
    "/config/outputs/0/items/0/dubTracks/0/language": [
      "No translation has ttsOptions, so there is no dub to add: use useOriginalTracks for the input’s audio."
    ],
    "/config/outputs/0/items/0/nameTemplate": [
      "The name template must contain ${name}, or every input would write the same file."
    ],
    "/config/translations/0/language": [
      "Language 'xx' is not supported by engine 'DeepL'"
    ]
  }
}

{
  "message": [
    "Too Many Attempts."
  ],
  "code": "too_many_requests"
}

Projects

Create a project

Creates a project and starts its processing service, unless options.autoStart is false. The config is checked in full first, and every problem is answered at once. Also accepted as YAML (Content-Type: application/yaml).

The config’s sourceMedia says where the media comes from: the project’s input folder (S3FolderSource, also what a config without one gets), an RSS feed (RssSource, the media in each item’s <enclosure>) or a Media RSS feed (MrssSource, each item’s <media:content>). Its outputs say where the results go: the output folder (S3FolderOutput) and, for a feed project, re-published feeds (RssOutput or MrssOutput, served at GET /feeds/{id}/{language}/feed.xml).

Each call creates a project, even with the same name. To repeat a create safely after a timeout or a dropped connection, send an Idempotency-Key: a repeat with the same key and body answers what the first call did, with Idempotency-Replayed: true, and creates nothing. Or look the name up with GET /projects?name= before creating it again. If the config is valid but the service does not start, the project is kept in error and the 422 carries its id: call POST /projects/{id}/start, not create.

Guide: The project config

POST

projects

Create a project

curl --request POST \
  --url https://api-vod-express.syncwords.com/v1/projects \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Fishing Channel S01",
  "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": "Spanish"
              }
            ]
          }
        ]
      }
    ]
  }
}
'

import requests

url = "https://api-vod-express.syncwords.com/v1/projects"

payload = {
    "name": "Fishing Channel S01",
    "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": "Spanish"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Fishing Channel S01',
    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: 'Spanish'}]
            }
          ]
        }
      ]
    }
  })
};

fetch('https://api-vod-express.syncwords.com/v1/projects', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "id": "01m3k8jnrdw509457nhz7w81bq",
    "name": "Fishing Channel S01",
    "description": null,
    "buildVersion": "0.9.0-alpha1-2026-10-20T14-10Z-3f05aa",
    "status": "running",
    "files": {
      "total": 3,
      "pending": 1,
      "processing": 0,
      "done": 1,
      "failed": 1,
      "countedAt": "2026-09-28T06:15:00.000Z"
    },
    "startOnNewFiles": true,
    "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": "Spanish"
                }
              ]
            }
          ]
        }
      ]
    },
    "storage": {
      "connection": null,
      "path": "s3://sw-vod-express/projects/141/01m3k8jnrdw509457nhz7w81bq/",
      "inputPath": "s3://sw-vod-express/projects/141/01m3k8jnrdw509457nhz7w81bq/input/",
      "outputPath": "s3://sw-vod-express/projects/141/01m3k8jnrdw509457nhz7w81bq/output/",
      "inputPrefix": null,
      "outputPrefix": null
    },
    "meta": {
      "createdAt": "2026-09-28T05:42:35.534Z",
      "updatedAt": "2026-09-28T05:42:35.534Z",
      "createdBy": {
        "accountId": 141,
        "accountName": "Acme Media",
        "userId": null,
        "userEmail": null,
        "userFullName": null
      },
      "configLocked": false,
      "messages": []
    }
  }
}

{
  "message": "<string>",
  "code": "bad_request",
  "errors": {}
}

{
  "message": "Unauthenticated.",
  "code": "unauthenticated"
}

{
  "message": [
    "VOD Express is not enabled for your account."
  ],
  "code": "vod_express_not_enabled"
}

{
  "message": [
    "A request with this Idempotency-Key is still in progress. Retry it shortly."
  ],
  "code": "idempotency_in_progress"
}

{
  "message": [
    "The request body is too large."
  ],
  "code": "payload_too_large"
}

{
  "message": [
    "Send the body as JSON (Content-Type: application/json) or YAML (Content-Type: application/yaml)."
  ],
  "code": "unsupported_media_type"
}

{
  "code": "validation_failed",
  "message": "No translation has ttsOptions, so there is no dub to add: use useOriginalTracks for the input’s audio. (and 2 more errors)",
  "errors": {
    "/config/outputs/0/items/0/dubTracks/0/language": [
      "No translation has ttsOptions, so there is no dub to add: use useOriginalTracks for the input’s audio."
    ],
    "/config/outputs/0/items/0/nameTemplate": [
      "The name template must contain ${name}, or every input would write the same file."
    ],
    "/config/translations/0/language": [
      "Language 'xx' is not supported by engine 'DeepL'"
    ]
  }
}

{
  "message": [
    "Too Many Attempts."
  ],
  "code": "too_many_requests"
}

Authorizations

Authorization

string

header

required

A token from POST /token/create, made with your API key pair.

Headers

Idempotency-Key

string

Any string of your choice, unique per project you mean to create: a UUID is a good one. A repeat of the call with the same key and body answers what the first call did and creates nothing. The same key with another body is refused (idempotency_key_reused). Keys belong to your account and are kept for 24 hours. A key whose call created nothing (a 4xx other than service_start_failed, or a 5xx) can be used again.

Required string length: 1 - 255

Pattern: ^[!-~]+$

Body

name

string

required

Your name for the project. Need not be unique.

Maximum string length: 255

config

Config · object

required

The processing instructions, validated against the schema of the project’s build. Shown here: build 0.9.0-alpha1-2026-10-20T14-10Z-3f05aa; GET /schema has any build’s.

Show child attributes

description

string | null

Maximum string length: 2000

buildVersion

string

The build to run on, from GET /build-versions. Left out, your account’s default.

startOnNewFiles

boolean

default:true

When the project is stopped and a new file lands in its input folder, start it: at once when an API upload completes, and within a minute when the project stopped itself after its last file and the file came another way (the AWS CLI, an SDK, a one-PUT upload). False: new files wait for POST …/start. Retrying a file starts the project either way. See Auto-stop.

storage

object

Where the project keeps its input and output folders: one of your storage connections — your own bucket — with a folder for each, or connectionId: null for SyncWords’ storage. Left out on create, your account’s default decides; left out on a change, nothing moves. A project on your own bucket reads its input folder and writes its output folder: no feed source, no feed outputs.

Show child attributes

options

object

Instructions for the create itself: acted on once, not stored, not returned. Refused on PUT/PATCH.

Show child attributes

Response

Created

data

object

required

Show child attributes

Overview

Account

Schema

Projects

Files

Feeds

Uploads

Webhooks

Create a project

Authorizations

Headers

Body

Response