Videos

Upload video files to the Clipzy ML Engine for processing and style extraction.

POST /api/v1/videos/upload

Upload a video file to the engine. The returned video_id is required when creating a processing job.

This endpoint uses multipart/form-data. Do not set Content-Type: application/json on this request — let your HTTP client set the multipart boundary automatically.

Supported formats: mp4, mov, avi, mkv, webm

Request parameters

file · file · required

The video file to upload. Must be one of the supported container formats: mp4, mov, avi, mkv, or webm.

template_video_id · string

The video_id of a previously uploaded video to use as a style template. When provided, the engine extracts the visual and audio style from this video and applies it during job processing.

webhook_url · string

A URL the engine will send a POST request to when processing for this video completes. The payload uses the standard response envelope with the job result as data.

Response fields

success · boolean · required

true on successful upload.

message · string · required

Human-readable confirmation message.

data · object · required

Hide properties

video_id · string · required

Unique identifier for the uploaded video. Pass this value as video_id when creating a job.

filename · string · required

The original filename of the uploaded file.

file_size_bytes · integer · required

Size of the uploaded file in bytes.

uploaded_at · string · required

ISO 8601 timestamp indicating when the file was received (e.g., "2024-04-05T10:30:00Z").

storage_url · string · required

Internal URL where the file is stored within the engine. This is an engine-internal reference and is not directly accessible from outside the service.

metadata · object · required

Technical properties extracted from the video file.

Show properties

width · integer · required

Video frame width in pixels.

height · integer · required

Video frame height in pixels.

duration_seconds · float · required

Total duration of the video in seconds.

frame_rate · float · required

Playback frame rate in frames per second (fps).

codec · string · required

Video codec used to encode the file (e.g., h264, h265).

bitrate_kbps · integer · required

Video bitrate in kilobits per second.

format · string · required

Container format of the file (e.g., mp4, mov).

Example request

cURL

curl --request POST \
  --url http://{host}/api/v1/videos/upload \
  --form "file=@/path/to/video.mp4" \
  --form "template_video_id=vid_abc123" \
  --form "webhook_url=https://example.com/webhooks/clipzy"

Example response

{
  "success": true,
  "message": "Video uploaded successfully",
  "data": {
    "video_id": "vid_abc123",
    "filename": "my-video.mp4",
    "file_size_bytes": 52428800,
    "uploaded_at": "2024-04-05T10:30:00Z",
    "storage_url": "internal://storage/videos/vid_abc123",
    "metadata": {
      "width": 1920,
      "height": 1080,
      "duration_seconds": 60.0,
      "frame_rate": 30.0,
      "codec": "h264",
      "bitrate_kbps": 8000,
      "format": "mp4"
    }
  }
}