Skip to main content

​
Overview

Single downloads are the core feature of Tornado. Submit a video URL and receive a processed file uploaded to S3.

​
Supported Options

ParameterTypeRequiredDescription
urlstringYesThe video URL to download
formatstringNoOutput format: mp4, mkv, mp3 (default: mp4)
filenamestringNoCustom filename (without extension)
folderstringNoS3 folder prefix for organization
webhook_urlstringNoURL to receive completion notification

​
Basic Request

curl -X POST "https://tornado.velys.software/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://tornado.velys.software/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

1

Queue

Job is added to the processing queue
2

Download

Video and audio streams are downloaded in parallel using optimal quality
3

Mux

FFmpeg combines video + audio into the final format
4

Upload

File is uploaded to S3 with multipart upload for large files
5

Complete

Webhook is called (if configured) and status is updated

​
Quality Selection

Tornado automatically selects the best available quality:
PriorityResolutionCodec
12160p (4K)VP9/AV1
21440p (2K)VP9/H.264
31080p (FHD)H.264
4720p (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"
}
The filename is automatically sanitized:
  • 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"
}
This creates the S3 key: client-a/project-1/videos/video-title.mp4
Folder names cannot contain .. or start with / for security.

​
Error Handling

Common errors and solutions:
ErrorCauseSolution
Video unavailablePrivate or deleted videoVerify the URL is accessible
Sign in to confirmAge-restricted contentContact us for cookie support
Rate limitedToo many requestsWait and retry, we handle rotation
Unsupported URLPlatform not supportedCheck supported platforms list