Single Downloads

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

Selection depends on max_resolution, requested codecs/format, source availability and account limits. A requested resolution is a cap, not a guarantee that the source offers that rendition. Inspect the job’s actual_quality and codec fields after completion. Audio selection also depends on the available streams and output format. Requesting an audio codec may require conversion; there is no fixed bitrate guaranteed for every source.

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 object path: 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

Get Started

Features

Storage guides

Integrations

Overview

Supported Options

Basic Request

With All Options

Processing Pipeline

Quality Selection

Custom Filenames

Folder Organization

Error Handling

​Overview

​Supported Options

​Basic Request

​With All Options

​Processing Pipeline

​Quality Selection

​Custom Filenames

​Folder Organization

​Error Handling

Overview

Supported Options

Basic Request

With All Options

Processing Pipeline

Quality Selection

Custom Filenames

Folder Organization

Error Handling