Overview
Single downloads are the core feature of Tornado. Submit a video URL and receive a processed file uploaded to your cloud storage.
Supported Options
| Parameter | Type | Required | Description |
|---|
url | string | Yes | The video URL to download |
format | string | No | Output format: mp4, mkv, webm, mov, m4a, mp3, ogg, opus (default: mp4) |
filename | string | No | Custom filename (without extension) |
folder | string | No | Folder prefix for organization |
webhook_url | string | No | URL to receive completion notification |
audio_only | boolean | No | Extract audio only (default format: m4a) |
max_resolution | string | No | Max resolution: best, 2160, 1440, 1080, 720, 480, 360 |
Basic Request
curl -X POST "https://api.tornadoapi.io/jobs" \
-H "x-api-key: sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}'
With All Options
curl -X POST "https://api.tornadoapi.io/jobs" \
-H "x-api-key: sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"format": "mp4",
"filename": "my-custom-video",
"folder": "youtube-downloads/2024",
"webhook_url": "https://myapp.com/webhook"
}'
Processing Pipeline
Queue
Job is added to the processing queue
Download
Video and audio streams are downloaded in parallel using optimal quality
Mux
FFmpeg combines video + audio into the final format
Upload
File is uploaded to your cloud storage with multipart/resumable upload for large files
Complete
Webhook is called (if configured) and status is updated
Quality Selection
Tornado automatically selects the best available quality:
| Priority | Resolution | Codec |
|---|
| 1 | 2160p (4K) | VP9/AV1 |
| 2 | 1440p (2K) | VP9/H.264 |
| 3 | 1080p (FHD) | H.264 |
| 4 | 720p (HD) | H.264 |
Audio is always downloaded at the highest available bitrate (usually 128-256 kbps).
Custom Filenames
Use the filename parameter to set a custom name:
{
"url": "https://youtube.com/watch?v=...",
"filename": "Episode 1 - Introduction"
}
- Special characters are removed
- Spaces are preserved
- Extension is added based on format
Folder Organization
Organize downloads into folders using the folder parameter:
{
"url": "https://youtube.com/watch?v=...",
"folder": "client-a/project-1/videos"
}
client-a/project-1/videos/video-title.mp4
Folder names cannot contain .. or start with / for security.
Error Handling
Common errors and solutions:
| Error | Cause | Solution |
|---|
Video unavailable | Private or deleted video | Verify the URL is accessible |
Sign in to confirm | Age-restricted content | Contact us for cookie support |
Rate limited | Too many requests | Wait and retry, we handle rotation |
Unsupported URL | Platform not supported | Check supported platforms list |
