API Documentation
The VideoSplit API allows you to programmatically split video files into equal-length segments. Built on REST principles with predictable URLs and JSON responses.
http://your-server.com
Supported Formats
MP4, MOV, AVI, MKV, FLV, WMV (max 500MB)
Quick Start
Get started with the VideoSplit API in minutes. Choose your language:
import requests
API_KEY = "vs_live_YOUR_API_KEY_HERE" # From Dashboard â API Keys
headers = {"Authorization": API_KEY}
# Upload and split video
url = "http://your-server.com/api/v1/split"
with open("video.mp4", "rb") as video_file:
files = {"file": video_file}
params = {"segment_duration": 30}
response = requests.post(url, files=files, params=params, headers=headers)
result = response.json()
print(f"Created {result['segments_count']} segments")
# Download each segment
for segment in result["segments"]:
download_url = "http://your-server.com" + segment["download_url"]
seg_response = requests.get(download_url)
with open(segment["filename"], "wb") as f:
f.write(seg_response.content)
print(f"Downloaded: {segment['filename']}")
const API_KEY = 'vs_live_YOUR_API_KEY_HERE'; // From Dashboard â API Keys
// Get file from input element
const file = document.getElementById('videoFile').files[0];
// Create form data
const formData = new FormData();
formData.append('file', file);
// Upload and split
const url = 'http://your-server.com/api/v1/split?segment_duration=30';
fetch(url, {
method: 'POST',
headers: { 'Authorization': API_KEY },
body: formData
})
.then(response => response.json())
.then(result => {
console.log(`Created ${result.segments_count} segments`);
// Download each segment
result.segments.forEach(segment => {
const link = document.createElement('a');
link.href = `http://your-server.com${segment.download_url}`;
link.download = segment.filename;
link.click();
});
})
.catch(error => console.error('Error:', error));
const fs = require('fs');
const FormData = require('form-data');
const axios = require('axios');
const API_KEY = 'vs_live_YOUR_API_KEY_HERE'; // From Dashboard â API Keys
async function splitVideo() {
// Create form data
const form = new FormData();
form.append('file', fs.createReadStream('video.mp4'));
const url = 'http://your-server.com/api/v1/split?segment_duration=30';
try {
// Upload and split
const response = await axios.post(url, form, {
headers: { ...form.getHeaders(), 'Authorization': API_KEY }
});
const result = response.data;
console.log(`Created ${result.segments_count} segments`);
// Download each segment
for (const segment of result.segments) {
const downloadUrl = `http://your-server.com${segment.download_url}`;
const segResponse = await axios.get(downloadUrl, { responseType: 'stream' });
segResponse.data.pipe(fs.createWriteStream(segment.filename));
console.log(`Downloaded: ${segment.filename}`);
}
} catch (error) {
console.error('Error:', error.message);
}
}
splitVideo();
# Replace with your API key from Dashboard â API Keys
API_KEY="vs_live_YOUR_API_KEY_HERE"
# Split video into 30-second segments
curl -X POST "http://your-server.com/api/v1/split?segment_duration=30" \
-H "Authorization: $API_KEY" \
-F "[email protected]" \
-o response.json
# View the response
cat response.json
# Download first segment (replace job_id from response)
curl -O "http://your-server.com/api/v1/download/{job_id}/segment_000.mp4"
# Download all segments as ZIP
curl -O "http://your-server.com/api/v1/download-all/{job_id}"
<?php
$api_key = "vs_live_YOUR_API_KEY_HERE"; // From Dashboard â API Keys
// API endpoint
$url = "http://your-server.com/api/v1/split?segment_duration=30";
// Prepare file upload
$video_path = "video.mp4";
$cfile = new CURLFile($video_path, 'video/mp4', basename($video_path));
// Create POST data
$data = array('file' => $cfile);
// Initialize cURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: $api_key"]);
// Execute request
$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($http_code == 200) {
$result = json_decode($response, true);
echo "Created " . $result['segments_count'] . " segments\n";
// Download each segment
foreach ($result['segments'] as $segment) {
$download_url = "http://your-server.com" . $segment['download_url'];
$filename = $segment['filename'];
$seg_data = file_get_contents($download_url);
file_put_contents($filename, $seg_data);
echo "Downloaded: $filename\n";
}
} else {
echo "Error: " . $response . "\n";
}
?>
Authentication
All API endpoints require authentication. VideoSplit supports two methods:
1. JWT Bearer Token (Web / Short-lived)
Obtain a token via POST /auth/login, then include it in every request:
Authorization: Bearer <your_access_token>
Access tokens expire after 30 minutes. Refresh using:
POST /auth/refresh
Content-Type: application/json
{ "refresh_token": "<your_refresh_token>" }
2. API Key (Programmatic / Long-lived)
Create an API key in your dashboard. Keys start with vs_live_.
Authorization: vs_live_<your_api_key>
2. Go to Dashboard â API Keys â Create New Key.
3. Copy the key immediately â it is shown only once.
Authentication Errors
| Code | Reason | Fix |
|---|---|---|
| 401 | Missing or invalid token/key | Check your Authorization header |
| 402 | Monthly quota exceeded | Upgrade your plan at /static/plans.html |
| 429 | Rate limit exceeded | Reduce request frequency; see Rate Limits section |
Plan Comparison
| Plan | Minutes/Month | Splits/Min | API Access | Price |
|---|---|---|---|---|
| FREE | 100 | 5 | â | $0 |
| STARTER | 1,000 | 20 | â | $19/mo |
| PRO | Unlimited | 60 | â | $49/mo |
| ENTERPRISE | Unlimited | 200 | â | Custom |
See the pricing page for full details.
Split Video
Upload a video file and split it into equal-length segments.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| file | File | Required | Video file to upload (multipart/form-data) |
| segment_duration | Integer | Optional | Duration of each segment in seconds (1-3600, default: 60) |
Returns
Returns a job object with segment details.
Example Response
{
"job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"segments_count": 3,
"segments": [
{
"filename": "segment_000.mp4",
"duration": 30.0,
"size_bytes": 5242880,
"download_url": "/api/v1/download/a1b2c3d4.../segment_000.mp4"
}
],
"original_filename": "video.mp4",
"total_duration": 75.5
}
Download Segment
Download a specific video segment by job ID and filename.
Path Parameters
| job_id | String | Required | Job ID from split response |
| filename | String | Required | Segment filename (e.g., segment_000.mp4) |
Returns
Returns the video file as binary data.
Download All Segments
Download all segments for a job as a single ZIP file.
Path Parameters
| job_id | String | Required | Job ID from split response |
Returns
Returns a ZIP file containing all segments.
Get Job Information
Retrieve information about a processing job.
Path Parameters
| job_id | String | Required | Job ID to retrieve |
Delete Job
Permanently delete a job and all its segments.
Error Handling
The API uses standard HTTP response codes to indicate success or failure.
| Code | Status | Description |
|---|---|---|
| 200 | OK | Request succeeded |
| 400 | Bad Request | Invalid parameters or file type |
| 404 | Not Found | Job or file doesn't exist |
| 500 | Server Error | Video processing failed |
Error Response Format
{
"detail": "Error message here"
}
Best Practices
Segment Duration
Choose appropriate segment durations for your use case:
- 5-30 seconds: Social media clips
- 30-120 seconds: Short-form content
- 2-10 minutes: Tutorial segments
Download Strategy
Use the ZIP download endpoint when you need multiple segments to save bandwidth and time.
Storage
Segments are kept for 24 hours. Download them promptly to avoid data loss.
Rate Limits
Rate limits are enforced per user per minute on the split endpoint:
| Plan | Splits / Minute |
|---|---|
| FREE | 5 |
| STARTER | 20 |
| PRO | 60 |
| ENTERPRISE | 200 |
When exceeded, the API returns 429 Too Many Requests with a Retry-After: 60 header. Wait one minute before retrying.