Skip to main content

​
Overview

Tornado supports advanced download options including audio-only extraction, resolution selection, video clipping, and live stream recording.

​
Audio-Only Extraction

Extract just the audio track from any video. By default, the audio is saved as m4a (native AAC from YouTube) with no re-encoding for maximum quality and speed.

​
Default (m4a, no re-encoding)

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",
    "audio_only": true
  }'

​
MP3 Output

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",
    "audio_only": true,
    "format": "mp3",
    "audio_bitrate": "320k"
  }'

​
Audio Formats

FormatCodecRe-encodingNotes
m4aAACNoDefault. Native YouTube format, fastest
mp3MP3YesUniversal compatibility
oggOpusYesSmaller files, great quality
opusOpusYesSame as ogg
Use m4a (default) for the fastest processing since it skips re-encoding entirely. Use mp3 only if you need broad device compatibility.
audio_only can be combined with clip_start/clip_end to extract a specific audio segment, and with audio_bitrate to control output quality.

​
Resolution Selection

Limit the maximum video resolution to reduce file size and download time.

​
Available Resolutions

ValueResolutionLandscapePortrait (Shorts)
bestMaximumHighest available (default)Highest available
21604K UHD3840x21602160x3840
14402K QHD2560x14401440x2560
1080Full HD1920x10801080x1920
720HD1280x720720x1280
480SD854x480480x854
360Low640x360360x640
max_resolution checks the shorter dimension of the video. This means 1080 correctly keeps both 1920x1080 landscape videos and 1080x1920 vertical videos (YouTube Shorts), while filtering out anything above 1080p in either orientation.

​
Example

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",
    "max_resolution": "720"
  }'
If the requested resolution is not available, Tornado downloads the next best available quality.

​
Video Clipping

Extract a specific segment from a video using start and end timestamps.

​
Timestamp Formats

Both formats are supported:
  • HH:MM:SS - Hours, minutes, seconds (e.g., 01:30:45)
  • Seconds - Raw seconds (e.g., 5445)

​
Examples

# Extract 1:30 to 3:00
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",
    "clip_start": "00:01:30",
    "clip_end": "00:03:00"
  }'

# Extract first 60 seconds
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",
    "clip_start": "0",
    "clip_end": "60"
  }'

# Extract from 5 minutes to end
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",
    "clip_start": "00:05:00"
  }'
clip_end must be greater than clip_start. Invalid timestamps will return a 400 error.

​
Live Stream Recording

Record ongoing YouTube or Twitch live streams.

​
Parameters

ParameterTypeDescription
live_recordingbooleanEnable live stream mode
live_from_startbooleanRecord from stream beginning (VOD mode)
max_durationintegerMaximum recording duration in seconds
wait_for_videobooleanWait for scheduled streams to start

​
Basic Live Recording

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/live/abc123",
    "live_recording": true,
    "max_duration": 3600
  }'

​
Record from Start (VOD Mode)

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/live/abc123",
    "live_recording": true,
    "live_from_start": true,
    "max_duration": 7200
  }'

​
Wait for Scheduled Stream

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=scheduled_stream_id",
    "live_recording": true,
    "wait_for_video": true,
    "max_duration": 3600
  }'
Always set max_duration for live streams to prevent indefinite recordings. Recommended: 2-4 hours maximum.

​
Combining Options

You can combine multiple options in a single 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",
    "max_resolution": "1080",
    "clip_start": "00:00:30",
    "clip_end": "00:02:00",
    "format": "mp4",
    "webhook_url": "https://myapp.com/webhook",
    "enable_progress_webhook": true
  }'

​
Error Handling

​
Invalid Resolution

{
  "error": "Invalid resolution '4k'. Valid options: [\"best\", \"2160\", \"1440\", \"1080\", \"720\", \"480\", \"360\"]"
}

​
Invalid Timestamps

{
  "error": "Invalid clip_start format 'abc'. Use HH:MM:SS or seconds"
}

{
  "error": "clip_end must be greater than clip_start"
}