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
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
videoName | string | No | Auto-generated | Custom name for the video |
fileUrl | string (URL) | Conditional | - | Single video URL to process |
files | array | Conditional | - | Multiple files to combine (requires combine: true) |
combine | boolean | No | false | Combine multiple videos into one |
webhookUrl | string (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
| Parameter | Type | Default | Description |
|---|---|---|---|
removeSilence | boolean | false | Remove silent segments from the video |
normalizeAudio | boolean | false | Normalize audio levels for consistent volume |
removeNoise | boolean | false | Remove background noise from audio |
AI Features
| Parameter | Type | Default | Description |
|---|---|---|---|
enableTranscription | boolean | false | Generate transcript |
enableAiAnalysis | boolean | false | Analyze video content with AI |
enableThumbnail | boolean | false | Generate thumbnail from video |
Output Format & Quality
| Parameter | Type | Default | Options | Description |
|---|---|---|---|---|
outputFormat | string | 'mp4' | 'mp4', 'mov', 'avi', 'webm' | Output video format |
compressionQuality | number | 100 | 1-100 | Compression quality (100 = original) |
Video Transformation
| Parameter | Type | Default | Options | Description |
|---|---|---|---|---|
aspectRatio | string | 'original' | 'original', '16:9', '9:16', '1:1', '4:5', '4:3', '21:9' | Target aspect ratio |
resizeMode | string | 'cover' | 'cover', 'contain', 'stretch' | How to resize video |
backgroundColor | string | '#000000' | Hex color | Background 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
| Field | Type | Description |
|---|---|---|
videoId | string | Unique identifier for the video |
jobId | string | Unique identifier for the processing job |
status | string | Current status: 'queued' |
message | string | Human-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:
fileUrlis not used (file is uploaded)filesarray is not supported (use URL endpoint for combining)combineis 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
| Parameter | Type | Required | Description |
|---|---|---|---|
videoId | string | Yes | Video 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
| Field | Type | Description |
|---|---|---|
videoId | string | Unique video identifier |
videoName | string | Video name |
status | string | Status: 'queued', 'running', 'succeeded', 'failed', 'canceled' |
progressPercent | number | Processing progress (0-100) |
finalVideoUrl | string | Download URL (available when status = 'succeeded') |
thumbnailUrl | string | Thumbnail URL (if enabled) |
hasTranscript | boolean | Whether transcript is available |
errorMessage | string | Error message (if status = 'failed') |
createdAt | string | ISO 8601 timestamp |
lastUpdatedAt | string | ISO 8601 timestamp |
Video Metadata
| Field | Type | Description |
|---|---|---|
videoMetadata.width | number | Video width in pixels |
videoMetadata.height | number | Video height in pixels |
videoMetadata.duration | number | Duration in seconds |
videoMetadata.fps | number | Frames per second |
videoMetadata.sizeInBytes | number | File size in bytes |
Analysis Object
| Field | Type | Description |
|---|---|---|
analysis.status | string | 'not_requested', 'pending', 'processing', 'completed', 'failed' |
analysis.progress | number | Analysis progress (0-100) |
analysis.data.tags | string[] | AI-generated content tags |
analysis.data.summary | string | Video content summary |
analysis.data.estimatedLocation | string | Estimated location/setting |
analysis.error | string | Error message (if failed) |
Transcript Object
| Field | Type | Description |
|---|---|---|
transcript.status | string | 'pending', 'processing', 'completed', 'failed' |
transcript.text | string | Full transcript text |
transcript.language | string | Detected language code |
transcript.transcriptUrl | string | URL 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
| Parameter | Type | Required | Description |
|---|---|---|---|
videoId | string | Yes | Video 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
| Field | Type | Description |
|---|---|---|
videoId | string | Video identifier |
text | string | Full transcript text |
language | string | Detected language code (e.g., 'en', 'es', 'fr') |
transcriptUrl | string | URL to download transcript file |
createdAt | string | ISO 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
| Code | Description |
|---|---|
| 200 | Success - Resource retrieved |
| 202 | Accepted - Video queued for processing |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid API key |
| 404 | Not Found - Resource doesn't exist |
| 413 | Payload Too Large - File exceeds size limit |
| 422 | Unsupported Media Type - Invalid file format |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal 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: 1609459200If you need higher rate limits, contact support to discuss enterprise plans.