Tusd protocol for uploading to our servers
Replace Video – Single Request Upload
This endpoint allows you to replace the content of an existing video while preserving its embed ID, statistics, and references.
It follows the same upload flow as the standard Tus protocol, but with additional metadata parameters required to control replacement options.
Headers
| Headers params | Type | Description |
|---|---|---|
| Tus-Resumable | String | The Tus-Resumable header MUST be included in every request and response with value 1.0.0 |
| Upload-Length | Number | The Upload-Length header indicates the size of the entire upload in bytes. |
| Content-Type | String | application/offset+octet-stream |
| Upload-Metadata | String | The Upload-Metadata request and response header MUST consist of one or more comma-separated key-value pairs. The key and value MUST be separated by a space. The key MUST NOT contain spaces and commas and MUST NOT be empty. The key SHOULD be ASCII encoded and the value MUST be Base64 encoded. All keys MUST be unique. In these cases, the space, which would normally separate the key and the value, MAY be left out. ⚠️ Mandatory metadata: should_replace (true or false) replace_video_options (see replacement modes below) replace_video_external_id (external ID reference for tracking) replace_video_id (ID of the video being replaced)" |
Replacement Options
When replacing a video, you can control how AI resources (e.g., subtitles, thumbnails, smart previews) and additional resources (ads, CTA overlays, extra configurations) are handled.
Available values for replace_video_options:
| Option | Description |
|---|---|
regenerate_ai_keep_options | Regenerate AI resources (subtitles, dubbings) and keep additional resources (CTAs, video configs). |
regenerate_ai_remove_options | Regenerate AI resources and discard additional resources. |
keep_options | Keep AI resources and keep additional resources. |
remove_config_options | Keep AI resources but discard additional resources. |
remove_ai_options | Discard AI resources but keep additional resources. |
remove_options | Discard both AI resources and additional resources. |
⚠️ AI resources = automatically generated assets by our system (captions, transcripts, AI thumbnails, etc.)
⚠️ Additional resources = user-configured assets such CTAs and external configurations.
Usage Example
You can check a working example in our GitHub repository.
Uploader URL
Please note the endpoint URL here is different from the regular API endpoints.
You are interacting directly with the upload servers, which are distributed across multiple regions.
Make sure to consult the list of Uploader Servers before starting your upload.
Reference
For more details about the upload flow, please check the official Tus protocol documentation.