Advanced Options

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

Format	Codec	Re-encoding	Notes
`m4a`	AAC	No	Default. Native YouTube format, fastest
`mp3`	MP3	Yes	Universal compatibility
`ogg`	Opus	Yes	Smaller files, great quality
`opus`	Opus	Yes	Same 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

Value	Resolution	Landscape	Portrait (Shorts)
`best`	Maximum	Highest available (default)	Highest available
`2160`	4K UHD	3840x2160	2160x3840
`1440`	2K QHD	2560x1440	1440x2560
`1080`	Full HD	1920x1080	1080x1920
`720`	HD	1280x720	720x1280
`480`	SD	854x480	480x854
`360`	Low	640x360	360x640

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

Parameter	Type	Description
`live_recording`	boolean	Enable live stream mode
`live_from_start`	boolean	Record from stream beginning (VOD mode)
`max_duration`	integer	Maximum recording duration in seconds
`wait_for_video`	boolean	Wait 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"
}

Get Started

Features

Storage guides

Integrations

Overview

Audio-Only Extraction

Default (m4a, no re-encoding)

MP3 Output

Audio Formats

Resolution Selection

Available Resolutions

Example

Video Clipping

Timestamp Formats

Examples

Live Stream Recording

Parameters

Basic Live Recording

Record from Start (VOD Mode)

Wait for Scheduled Stream

Combining Options

Error Handling

Invalid Resolution

Invalid Timestamps

​Overview

​Audio-Only Extraction

​Default (m4a, no re-encoding)

​MP3 Output

​Audio Formats

​Resolution Selection

​Available Resolutions

​Example

​Video Clipping

​Timestamp Formats

​Examples

​Live Stream Recording

​Parameters

​Basic Live Recording

​Record from Start (VOD Mode)

​Wait for Scheduled Stream

​Combining Options

​Error Handling

​Invalid Resolution

​Invalid Timestamps

Overview

Audio-Only Extraction

Default (m4a, no re-encoding)

MP3 Output

Audio Formats

Resolution Selection

Available Resolutions

Example

Video Clipping

Timestamp Formats

Examples

Live Stream Recording

Parameters

Basic Live Recording

Record from Start (VOD Mode)

Wait for Scheduled Stream

Combining Options

Error Handling

Invalid Resolution

Invalid Timestamps