🎥 Uploading Videos

This guide explains the different methods available for uploading videos using the ZapCap API. Each method has its own benefits and use cases.

Available Upload Methods

1. Upload Video by URL
2. Direct Video Upload
3. Multipart Upload (Create Upload & Complete Upload)

1. Upload Video by URL

Endpoint: POST /videos/url

This method allows you to upload a video by providing a URL where the video is hosted.

Request Body:

{
  "url": "https://example.com/path/to/video.mp4"
}

Benefits:

• Convenient for videos already hosted online
• No need to download and re-upload the video
• Suitable for small-medium files without worrying about upload speed from your local machine

2. Direct Video Upload

Endpoint: POST /videos

This method allows you to directly upload a video file from your local machine or server.

Request Headers and Body:

• Content-Type: multipart/form-data; boundary=<boundary_string>
  • The boundary_string is a unique string that separates different parts of the multipart request.
• Body: Include the video file as form-data

How to set the Content-Type header in different languages:

1. cURL:

   curl -X POST "https://api.zapcap.ai/videos" \
     -H "Content-Type: multipart/form-data" \
     -H "x-api-key: YOUR_API_KEY" \
     -F "file=@/path/to/your/video.mp4"

   Note: cURL automatically generates and sets the boundary.

2. Python (using requests library):

   import requests
   
   url = "https://api.zapcap.ai/videos"
   files = {'file': open('path/to/your/video.mp4', 'rb')}
   headers = {
       'x-api-key': 'YOUR_API_KEY'
   }
   
   response = requests.post(url, files=files, headers=headers)

   Note: The requests library automatically sets the Content-Type header with the appropriate boundary.

3. JavaScript (using fetch API):

   const formData = new FormData();
   formData.append("file", fileInput.files[0]);
   
   fetch("https://api.zapcap.ai/videos", {
     method: "POST",
     headers: {
       "x-api-key": "YOUR_API_KEY",
     },
     body: formData,
   })
     .then((response) => response.json())
     .then((data) => console.log(data))
     .catch((error) => console.error("Error:", error));

   Note: The fetch API automatically sets the Content-Type header with the appropriate boundary when using FormData.

Benefits:

• Simple and straightforward for smaller files
• Useful when you have the video file locally and it's not too large
• Good for quick uploads without the need for multipart complexity

3. Multipart Upload

This method is split into two steps: initiating the upload and then completing it. It's ideal for large files.

Step 1: Create Upload

Endpoint: POST /videos/upload

Initiates a multipart upload session.

Request Body:

{
  "uploadParts": [
    { "contentLength": 10485760 }
    // Add more parts as needed
  ],
  "filename": "sample.mp4"
}

Response:

Provides uploadId, videoId, and presigned URLs for uploading each part. Refer to the API reference for more details.

Step 2: Complete Upload

Endpoint: POST /videos/upload/complete

Finalizes the multipart upload process.

Request Body:

{
  "uploadId": "upload_abc123",
  "videoId": "video_xyz789"
}

Complete Multipart Upload Examples

Here are complete examples showing how to upload large files using multipart upload:

Node.js

import axios from "axios";
import { createReadStream, statSync } from "fs";

const API_KEY = "YOUR_API_KEY";
const API_BASE = "https://api.zapcap.ai";
const CHUNK_SIZE = 10 * 1024 * 1024; // 10MB per part

async function multipartUpload(filePath) {
  const fileSize = statSync(filePath).size;
  const numParts = Math.ceil(fileSize / CHUNK_SIZE);

  // 1. Calculate part sizes
  const uploadParts = [];
  for (let i = 0; i < numParts; i++) {
    const start = i * CHUNK_SIZE;
    const end = Math.min(start + CHUNK_SIZE, fileSize);
    uploadParts.push({ contentLength: end - start });
  }

  // 2. Initialize multipart upload
  console.log(`Initializing upload with ${numParts} parts...`);
  const initResponse = await axios.post(
    `${API_BASE}/videos/upload`,
    {
      uploadParts,
      filename: filePath.split("/").pop(),
    },
    { headers: { "x-api-key": API_KEY } }
  );

  const { uploadId, videoId, parts } = initResponse.data;
  console.log("Upload initialized, videoId:", videoId);

  // 3. Upload each part using presigned URLs
  const fileStream = createReadStream(filePath, { highWaterMark: CHUNK_SIZE });
  let partIndex = 0;

  for await (const chunk of fileStream) {
    const { presignedUrl } = parts[partIndex];
    console.log(`Uploading part ${partIndex + 1}/${numParts}...`);

    await axios.put(presignedUrl, chunk, {
      headers: { "Content-Length": chunk.length },
    });
    partIndex++;
  }

  // 4. Complete the upload
  console.log("Completing upload...");
  await axios.post(
    `${API_BASE}/videos/upload/complete`,
    { uploadId, videoId },
    { headers: { "x-api-key": API_KEY } }
  );

  console.log("Upload complete! Video ID:", videoId);
  return videoId;
}

multipartUpload("/path/to/large-video.mp4");

Python

import requests
import os
import math

API_KEY = 'YOUR_API_KEY'
API_BASE = 'https://api.zapcap.ai'
CHUNK_SIZE = 10 * 1024 * 1024  # 10MB per part

def multipart_upload(file_path):
    file_size = os.path.getsize(file_path)
    num_parts = math.ceil(file_size / CHUNK_SIZE)

    # 1. Calculate part sizes
    upload_parts = []
    for i in range(num_parts):
        start = i * CHUNK_SIZE
        end = min(start + CHUNK_SIZE, file_size)
        upload_parts.append({'contentLength': end - start})

    # 2. Initialize multipart upload
    print(f'Initializing upload with {num_parts} parts...')
    init_response = requests.post(
        f'{API_BASE}/videos/upload',
        headers={'x-api-key': API_KEY},
        json={
            'uploadParts': upload_parts,
            'filename': os.path.basename(file_path)
        }
    )
    init_response.raise_for_status()
    data = init_response.json()
    upload_id = data['uploadId']
    video_id = data['videoId']
    parts = data['parts']
    print(f'Upload initialized, videoId: {video_id}')

    # 3. Upload each part using presigned URLs
    with open(file_path, 'rb') as f:
        for i, part in enumerate(parts):
            chunk = f.read(CHUNK_SIZE)
            print(f'Uploading part {i + 1}/{num_parts}...')

            response = requests.put(
                part['presignedUrl'],
                data=chunk,
                headers={'Content-Length': str(len(chunk))}
            )
            response.raise_for_status()

    # 4. Complete the upload
    print('Completing upload...')
    complete_response = requests.post(
        f'{API_BASE}/videos/upload/complete',
        headers={'x-api-key': API_KEY},
        json={'uploadId': upload_id, 'videoId': video_id}
    )
    complete_response.raise_for_status()

    print(f'Upload complete! Video ID: {video_id}')
    return video_id

multipart_upload('/path/to/large-video.mp4')

Benefits of Multipart Upload:

• Ideal for large files
• Allows for pause and resume of uploads
• Better handling of network interruptions
• Improved upload speeds for large files

General Notes

• All methods support an optional ttl query parameter (values: "1d", "7d", "30d") for specifying the Time to Live for the uploaded video.
• After successful upload, you'll receive a video ID which you can use to create video tasks for further processing.

Choosing the Right Method

• Upload by URL: Best for videos already hosted online or medium-sized` files.
• Direct Upload: Ideal for smaller files and quick, simple uploads.
• Multipart Upload: Recommended for large files, especially in environments with unreliable network connections.

Remember to check the API reference for any updates or additional parameters that may be required for each method.