Upload video

Send a video file to the Clipzy ML Engine API and receive a video_id to use in processing jobs.

Upload a video by sending a multipart/form-data POST request to /api/v1/videos/upload. The response returns a video_id you pass when creating a processing job.

Supported formats and limits

Property	Value
Accepted formats	mp4, mov, avi, mkv, webm
Maximum file size	Configurable (default: 1000 MB)

Uploading a file in an unsupported format or exceeding the configured size limit returns an error. Check your file before uploading.

Request fields

file · file · required

The video file to upload. Must be one of the supported formats.

template_video_id · string

The video_id of a previously uploaded template video. When provided, Clipzy uses this video’s style as the reference when you create a job. You can also supply this when creating the job instead.

webhook_url · string

A URL that Clipzy calls when a job using this video completes. See Webhooks for payload details.

Upload a video

1. Prepare your file

   Confirm your file is in a supported format (mp4, mov, avi, mkv, or webm) and within the size limit configured on your deployment (default: 1000 MB).

2. Send the request

   POST the file as multipart/form-data to the upload endpoint.

   cURL

   curl -X POST http://localhost:8000/api/v1/videos/upload \
     -F "file=@/path/to/my_video.mp4" \
     -F "webhook_url=https://yourapp.com/webhooks/clipzy"
   
3. Read the response

   A successful upload returns HTTP 200 with the following body:

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

   Save the video_id — you need it to create a processing job.

Response fields

data.video_id · string · required

Unique identifier for the uploaded video. Pass this to POST /api/v1/jobs as video_id.

data.filename · string

The original filename as received by the server.

data.file_size_bytes · number

Size of the uploaded file in bytes.

data.metadata · object

Technical properties extracted from the video file.

Show metadata properties

width · number

Pixel width.

height · number

Pixel height.

duration_seconds · number

Total duration in seconds.

frame_rate · number

Frames per second.

codec · string

Video codec (e.g. h264).

bitrate_kbps · number

Bitrate in kilobits per second.

format · string

Container format (e.g. mp4).

data.uploaded_at · string

ISO 8601 timestamp of when the upload completed.

data.storage_url · string

Internal storage path for the uploaded file.

Error cases

Errors follow the standard error format:

{
  "success": false,
  "message": "Descriptive error message",
  "error": {
    "detail": "Technical details",
    "code": "ERROR_CODE"
  }
}

Unsupported format

If the file extension or MIME type is not supported, the API returns HTTP 422 with code: "UNSUPPORTED_FORMAT". Convert your file to mp4, mov, avi, mkv, or webm before retrying.

File too large

Files exceeding the MAX_FILE_SIZE_MB limit return HTTP 413 with code: "FILE_TOO_LARGE". Compress or trim your video, or ask your administrator to increase the limit.

Missing file field

Omitting the file field returns HTTP 422 with code: "MISSING_FIELD". Ensure your multipart body includes a file part.

Next steps

Once you have a video_id, create a processing job to start style analysis and rendering.