Upload a Video

POST /v1/videos/upload

Create a draft video record. You can upload a file directly, provide an existing video URL, or get a presigned URL for client-side upload.

Request body

The endpoint accepts either a multipart form-data body (for direct file upload) or a JSON body (for URL / presigned URL flows).

JSON body

Parameter	Type	Required	Description
videoUrl	string	No*	URL of an existing video
filename	string	No*	Original filename (non-empty)
contentType	string	No*	MIME type, must start with video/ (e.g. video/mp4)
name	string	No	Display name. Defaults to filename without extension
videoContext	string	No	Context about the video content (used during analysis)

* Provide either videoUrl or both filename and contentType.

Multipart form-data body

Field	Type	Required	Description
file	file	Yes	Video file (max 500 MB, must be video/*)
name	string	No	Display name. Defaults to filename without extension
videoContext	string	No	Context about the video content (used during analysis)

Option 1: Provide a video URL

If you already have a publicly accessible video, pass its URL directly:

curl -X POST https://api.vidocu.ai/v1/videos/upload \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://example.com/videos/product-demo.mp4",
    "name": "Product Demo Q1"
  }'

Response 201 Created

{
  "id": "vid_1708300000000_abc1234",
  "videoUrl": "https://example.com/videos/product-demo.mp4"
}

No uploadUrl is returned since the video is already hosted.

Option 2: Upload a file

If you need to upload a file, provide filename and contentType to get a presigned S3 URL:

curl -X POST https://api.vidocu.ai/v1/videos/upload \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "product-demo.mp4",
    "contentType": "video/mp4",
    "name": "Product Demo Q1",
    "videoContext": "A walkthrough of the new dashboard features"
  }'

Response 201 Created

{
  "id": "vid_1708300000000_abc1234",
  "uploadUrl": "https://storage.vidocu.ai/workspaces/.../api-uploads/1708300000000-product-demo.mp4?X-Amz-Algorithm=...",
  "videoUrl": "https://storage.vidocu.ai/workspaces/.../api-uploads/1708300000000-product-demo.mp4"
}

Then upload the file to the presigned URL:

curl -X PUT "UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @product-demo.mp4

The presigned URL expires after 1 hour.

Option 3: Upload a file directly

Send the video file as multipart form-data. The server uploads it to S3 for you — no extra steps needed.

curl -X POST https://api.vidocu.ai/v1/videos/upload \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -F "[email protected]" \
  -F "name=Product Demo Q1" \
  -F "videoContext=A walkthrough of the new dashboard features"

Response 201 Created

{
  "id": "vid_1708300000000_abc1234",
  "videoUrl": "https://storage.vidocu.ai/workspaces/.../api-uploads/1708300000000-product-demo.mp4"
}

Maximum file size is 500 MB. Only video/* MIME types are accepted.

Response fields

Field	Description
id	Unique video ID (format: vid_{timestamp}_{random})
uploadUrl	Presigned S3 PUT URL — only present when using file upload
videoUrl	URL where the video is accessible

Errors

Status	Code	Cause
400	validation_error	Must provide either videoUrl or both filename and contentType
401	authentication_error	Invalid or missing API key

Next step

After uploading, analyze the video to generate subtitles and metadata.