VideoCascadeLogo
VideoCascade

Video Processing Endpoints

Complete reference for video processing API endpoints

These endpoints handle video processing operations including creating videos from URLs, uploading files, checking status, and retrieving transcripts.


Create Video from URL

Process a video from a URL with optional AI features, audio enhancements, and visual transformations.

Endpoint: POST /v1/videos

Authentication: Required (Bearer token)

Request Body

All parameters are optional except either fileUrl or files (exactly one must be provided).

Basic Parameters

ParameterTypeRequiredDefaultDescription
videoNamestringNoAuto-generatedCustom name for the video
fileUrlstring (URL)Conditional-Single video URL to process
filesarrayConditional-Multiple files to combine (requires combine: true)
combinebooleanNofalseCombine multiple videos into one
webhookUrlstring (URL)No-URL to receive completion webhook

Either fileUrl or files must be provided, but not both. If using files, you must set combine: true.

Audio Processing

ParameterTypeDefaultDescription
removeSilencebooleanfalseRemove silent segments from the video
normalizeAudiobooleanfalseNormalize audio levels for consistent volume
removeNoisebooleanfalseRemove background noise from audio

AI Features

ParameterTypeDefaultDescription
enableTranscriptionbooleanfalseGenerate transcript
enableAiAnalysisbooleanfalseAnalyze video content with AI
enableThumbnailbooleanfalseGenerate thumbnail from video

Output Format & Quality

ParameterTypeDefaultOptionsDescription
outputFormatstring'mp4''mp4', 'mov', 'avi', 'webm'Output video format
compressionQualitynumber1001-100Compression quality (100 = original)

Video Transformation

ParameterTypeDefaultOptionsDescription
aspectRatiostring'original''original', '16:9', '9:16', '1:1', '4:5', '4:3', '21:9'Target aspect ratio
resizeModestring'cover''cover', 'contain', 'stretch'How to resize video
backgroundColorstring'#000000'Hex colorBackground color for letterboxing

Advanced Options

Remove Segments: Array of segments to remove from the video

"removeSegments": [
  {
    "startTime": 10.5,
    "endTime": 25.0
  }
]

Files Array: For combining multiple videos

"files": [
  {
    "url": "https://example.com/video1.mp4",
    "removeSegments": [{"startTime": 0, "endTime": 5}],
    "disableAudio": false
  },
  {
    "url": "https://example.com/video2.mp4",
    "disableAudio": false
  }
]

Elements: Add overlays like images, GIFs, videos, or audio (see Elements documentation)

Request Examples

curl -X POST https://api.videocascade.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "videoName": "My Processed Video",
    "fileUrl": "https://example.com/video.mp4",
    "removeSilence": true,
    "normalizeAudio": true,
    "enableTranscription": true,
    "enableAiAnalysis": true,
    "aspectRatio": "16:9",
    "outputFormat": "mp4",
    "compressionQuality": 85,
    "webhookUrl": "https://your-app.com/webhook"
  }'
const response = await fetch('https://api.videocascade.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    videoName: 'My Processed Video',
    fileUrl: 'https://example.com/video.mp4',
    removeSilence: true,
    normalizeAudio: true,
    enableTranscription: true,
    enableAiAnalysis: true,
    aspectRatio: '16:9',
    outputFormat: 'mp4',
    compressionQuality: 85,
    webhookUrl: 'https://your-app.com/webhook'
  })
});

const data = await response.json();
console.log('Video ID:', data.videoId);
console.log('Job ID:', data.jobId);
import requests

response = requests.post(
    'https://api.videocascade.com/v1/videos',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'videoName': 'My Processed Video',
        'fileUrl': 'https://example.com/video.mp4',
        'removeSilence': True,
        'normalizeAudio': True,
        'enableTranscription': True,
        'enableAiAnalysis': True,
        'aspectRatio': '16:9',
        'outputFormat': 'mp4',
        'compressionQuality': 85,
        'webhookUrl': 'https://your-app.com/webhook'
    }
)

data = response.json()
print(f"Video ID: {data['videoId']}")
print(f"Job ID: {data['jobId']}")

Response

Status Code: 202 Accepted

{
  "videoId": "v_abc12345",
  "jobId": "j_xyz67890",
  "status": "queued",
  "message": "Video accepted. Processing will begin soon."
}

Response Fields

FieldTypeDescription
videoIdstringUnique identifier for the video
jobIdstringUnique identifier for the processing job
statusstringCurrent status: 'queued'
messagestringHuman-readable status message

Error Responses

400 Bad Request - Invalid parameters

{
  "error": "ValidationError",
  "message": "Invalid request data",
  "details": [
    {
      "field": "fileUrl",
      "message": "Invalid URL format"
    }
  ]
}

401 Unauthorized - Missing or invalid API key

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

429 Too Many Requests - Rate limit exceeded

{
  "error": "RateLimitExceeded",
  "message": "Too many requests. Please try again later."
}

Upload Video File

Upload a video file directly for processing with the same options as URL-based processing.

Endpoint: POST /v1/videos/upload

Authentication: Required (Bearer token)

Content-Type: multipart/form-data

Request Parameters

File Field: file (required)

  • Maximum size: 2GB
  • Supported formats: MP4, MOV, AVI, WebM
  • File type is validated using magic bytes (not just extension)

Form Fields: All the same parameters as Create Video from URL except:

  • fileUrl is not used (file is uploaded)
  • files array is not supported (use URL endpoint for combining)
  • combine is not supported (always false)

Boolean fields must be sent as strings ('true' or 'false') in multipart form data.

Request Examples

curl -X POST https://api.videocascade.com/v1/videos/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/video.mp4" \
  -F "videoName=My Uploaded Video" \
  -F "removeSilence=true" \
  -F "normalizeAudio=true" \
  -F "enableTranscription=true" \
  -F "aspectRatio=16:9" \
  -F "outputFormat=mp4" \
  -F "compressionQuality=85"
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('videoName', 'My Uploaded Video');
formData.append('removeSilence', 'true');
formData.append('normalizeAudio', 'true');
formData.append('enableTranscription', 'true');
formData.append('aspectRatio', '16:9');
formData.append('outputFormat', 'mp4');
formData.append('compressionQuality', '85');

const response = await fetch('https://api.videocascade.com/v1/videos/upload', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
},
body: formData
});

const data = await response.json();
console.log('Video ID:', data.videoId);
import requests

files = {'file': open('/path/to/video.mp4', 'rb')}
data = {
    'videoName': 'My Uploaded Video',
    'removeSilence': 'true',
    'normalizeAudio': 'true',
    'enableTranscription': 'true',
    'aspectRatio': '16:9',
    'outputFormat': 'mp4',
    'compressionQuality': '85'
}

response = requests.post(
    'https://api.videocascade.com/v1/videos/upload',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    files=files,
    data=data
)

result = response.json()
print(f"Video ID: {result['videoId']}")

Response

Status Code: 202 Accepted

Same response format as Create Video from URL

Error Responses

400 Bad Request - No file or invalid file type

{
  "error": "ValidationError",
  "message": "Invalid video file format",
  "details": {
    "field": "file",
    "reason": "File type validation failed"
  }
}

413 Payload Too Large - File exceeds 2GB limit

{
  "error": "PayloadTooLarge",
  "message": "File size exceeds maximum allowed size"
}

422 Unsupported Media Type - Invalid file format

{
  "error": "UnsupportedMediaType",
  "message": "Unsupported file type. Please upload MP4, MOV, AVI, or WebM files."
}

Get Video Status

Retrieve the current status and details of a video processing job.

Endpoint: GET /v1/videos/{videoId}

Authentication: Required (Bearer token)

Path Parameters

ParameterTypeRequiredDescription
videoIdstringYesVideo ID returned from creation (format: v_xxxxxxxx)

Request Examples

curl -X GET https://api.videocascade.com/v1/videos/v_abc12345 \
  -H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch('https://api.videocascade.com/v1/videos/v_abc12345', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const video = await response.json();
console.log('Status:', video.status);
console.log('Progress:', video.progressPercent);

if (video.status === 'succeeded') {
console.log('Download URL:', video.finalVideoUrl);
}
import requests

response = requests.get(
    'https://api.videocascade.com/v1/videos/v_abc12345',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

video = response.json()
print(f"Status: {video['status']}")
print(f"Progress: {video['progressPercent']}%")

if video['status'] == 'succeeded':
    print(f"Download URL: {video['finalVideoUrl']}")

Response

Status Code: 200 OK

{
  "videoId": "v_abc12345",
  "videoName": "My Processed Video",
  "status": "succeeded",
  "progressPercent": 100,
  "finalVideoUrl": "https://storage.example.com/videos/final/v_abc12345.mp4",
  "thumbnailUrl": "https://storage.example.com/thumbnails/v_abc12345.jpg",
  "hasTranscript": true,
  "videoMetadata": {
    "width": 1920,
    "height": 1080,
    "duration": 125.5,
    "fps": 30,
    "sizeInBytes": 45678901
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastUpdatedAt": "2024-01-15T10:35:00.000Z",
  "combine": false,
  "removeSilence": true,
  "normalizeAudio": true,
  "removeNoise": false,
  "enableTranscription": true,
  "enableAiAnalysis": true,
  "enableThumbnail": true,
  "outputFormat": "mp4",
  "compressionQuality": 85,
  "aspectRatio": "16:9",
  "resizeMode": "cover",
  "backgroundColor": "#000000",
  "analysis": {
    "status": "completed",
    "progress": 100,
    "data": {
      "tags": ["outdoor", "nature", "hiking", "mountains"],
      "summary": "A scenic hiking video showcasing mountain trails and natural landscapes.",
      "estimatedLocation": "Mountain region"
    }
  },
  "transcript": {
    "status": "completed",
    "text": "Welcome to our hiking adventure...",
    "language": "en",
    "transcriptUrl": "https://storage.example.com/transcripts/v_abc12345.txt"
  }
}

Response Fields

Core Fields

FieldTypeDescription
videoIdstringUnique video identifier
videoNamestringVideo name
statusstringStatus: 'queued', 'running', 'succeeded', 'failed', 'canceled'
progressPercentnumberProcessing progress (0-100)
finalVideoUrlstringDownload URL (available when status = 'succeeded')
thumbnailUrlstringThumbnail URL (if enabled)
hasTranscriptbooleanWhether transcript is available
errorMessagestringError message (if status = 'failed')
createdAtstringISO 8601 timestamp
lastUpdatedAtstringISO 8601 timestamp

Video Metadata

FieldTypeDescription
videoMetadata.widthnumberVideo width in pixels
videoMetadata.heightnumberVideo height in pixels
videoMetadata.durationnumberDuration in seconds
videoMetadata.fpsnumberFrames per second
videoMetadata.sizeInBytesnumberFile size in bytes

Analysis Object

FieldTypeDescription
analysis.statusstring'not_requested', 'pending', 'processing', 'completed', 'failed'
analysis.progressnumberAnalysis progress (0-100)
analysis.data.tagsstring[]AI-generated content tags
analysis.data.summarystringVideo content summary
analysis.data.estimatedLocationstringEstimated location/setting
analysis.errorstringError message (if failed)

Transcript Object

FieldTypeDescription
transcript.statusstring'pending', 'processing', 'completed', 'failed'
transcript.textstringFull transcript text
transcript.languagestringDetected language code
transcript.transcriptUrlstringURL to download full transcript

Poll this endpoint to track processing progress. For long-running jobs, consider using webhooks instead.

Error Responses

404 Not Found - Video doesn't exist or doesn't belong to user

{
  "error": "NotFound",
  "message": "Video not found"
}

Get Video Transcript

Retrieve the full transcript for a video (if transcription was enabled).

Endpoint: GET /v1/videos/{videoId}/transcript

Authentication: Required (Bearer token)

Path Parameters

ParameterTypeRequiredDescription
videoIdstringYesVideo ID (format: v_xxxxxxxx)

Request Examples

curl -X GET https://api.videocascade.com/v1/videos/v_abc12345/transcript \
  -H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch('https://api.videocascade.com/v1/videos/v_abc12345/transcript', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const transcript = await response.json();
console.log('Language:', transcript.language);
console.log('Transcript:', transcript.text);
import requests

response = requests.get(
    'https://api.videocascade.com/v1/videos/v_abc12345/transcript',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

transcript = response.json()
print(f"Language: {transcript['language']}")
print(f"Transcript: {transcript['text']}")

Response

Status Code: 200 OK

{
  "videoId": "v_abc12345",
  "text": "Welcome to our hiking adventure. Today we're exploring the beautiful mountain trails...",
  "language": "en",
  "transcriptUrl": "https://storage.example.com/transcripts/v_abc12345.txt",
  "createdAt": "2024-01-15T10:35:00.000Z"
}

Response Fields

FieldTypeDescription
videoIdstringVideo identifier
textstringFull transcript text
languagestringDetected language code (e.g., 'en', 'es', 'fr')
transcriptUrlstringURL to download transcript file
createdAtstringISO 8601 timestamp of transcript creation

Error Responses

404 Not Found - Video or transcript doesn't exist

{
  "error": "NotFound",
  "message": "Video does not have a transcript"
}

Transcripts are only available if enableTranscription: true was set during video creation.


Status Codes Summary

CodeDescription
200Success - Resource retrieved
202Accepted - Video queued for processing
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
404Not Found - Resource doesn't exist
413Payload Too Large - File exceeds size limit
422Unsupported Media Type - Invalid file format
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server issue

Rate Limits

All video endpoints are rate-limited to prevent abuse. The default rate limit is:

  • 100 requests per minute per API key
  • 1000 requests per hour per API key

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

If you need higher rate limits, contact support to discuss enterprise plans.