Advanced Options

Overview

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

Re-encoding requires a paid account

Audio/video re-encoding is available with a paid subscription or pay-as-you-go outside its free trial. Adding a card during a trial does not unlock re-encoding. Downloads, stream-copy audio extraction, clipping without encoding, and merging existing audio/video streams remain available during the trial. A conversion request is an explicit video_codec or audio_codec (other than copy), audio_bitrate, video_quality, or format: "mp3". Another format alone (for example mp4, webm, m4a, ogg or opus) only selects compatible source streams: when the source already carries them, the file is delivered as requested, without notice. Otherwise, without the entitlement below, only the completed job carries the reencoding_notice. Without this entitlement, conversion requests are still accepted, including bulk submissions and retries. The file is delivered using the original codecs, with an optional reencoding_notice explaining that re-encoding requires a paid plan. This notice appears in creation responses, job results, and completion webhooks. The dashboard also displays it on the completed job. The worker ignores encoding settings such as audio_bitrate and video_quality and uses a container compatible with the source. Consequently, the delivered format and filename extension may differ from those requested. For example, an MP3 request with an AAC source can deliver an M4A file without converting audio. The job completes normally; this notice is not a job error. If the account’s entitlement cannot be verified at processing time, the job is not failed either: the file is delivered the same way, with a reencoding_notice stating that re-encoding was skipped because the entitlement could not be verified. Submit the request again later to get the conversion.

Audio-Only Extraction

Extract the audio track from a supported source. m4a is the usual audio-only output; set format explicitly when the container matters. Stream copying is possible when source and requested output match. Codec, bitrate and clipping options can require processing.

Audio-only 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",
    "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	Conditional	Compatible AAC sources can be copied; other sources/options require processing
`mp3`	MP3	Conditional	Conversion is needed when the source/options do not match
`ogg`	Opus by default	Conditional	Output codec can also be requested explicitly
`opus`	Opus	Conditional	Conversion depends on source codec and requested processing

Choose the format your consumer accepts. Source codec compatibility, requested bitrate and clipping determine whether re-encoding is necessary.

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
`240`	Lower	Source-dependent	Source-dependent
`144`	Lowest numeric cap	Source-dependent	Source-dependent
`lowest`	Smallest available	Source-dependent	Source-dependent

max_resolution checks the shorter dimension of the video. This means 1080 correctly keeps both 1920x1080 landscape videos and 1080x1920 vertical videos (YouTube Shorts), when a suitable rendition exists. If no format fits the cap, selection can fall back to the smallest available rendition, which can exceed it.

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"
  }'

A numeric value selects the best available rendition at or below the cap, or the smallest available rendition if none fits. Account limits and source availability still apply.

Video Clipping

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

Timestamp Formats

Timestamps are JSON strings. Supported forms include:

MM:SS - Minutes and seconds
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.

Several clips from one video

Submit one URL and a clips array to POST /jobs:

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",
    "clips": [
      {"clip_start": "0", "clip_end": "15"},
      {"clip_start": "00:01:00", "clip_end": "00:01:30"}
    ],
    "filename": "highlights",
    "format": "mp4"
  }'

This creates one job. The worker downloads the source once, then produces one separate file per range, in the same order. The filenames end in -clip-001.mp4, -clip-002.mp4, etc. All clips use the shared format, encoding and storage options; audio_only is supported. Poll GET /jobs/{job_id}. When the job completes, clip_files contains each range, object key, download URL and file size:

{
  "clip_files": [
    {"clip_start": "0", "clip_end": "15", "s3_key": "videos/.../highlights-clip-001.mp4", "s3_url": "https://storage.example/clip-001.mp4?signature=...", "file_size": 1250000},
    {"clip_start": "00:01:00", "clip_end": "00:01:30", "s3_key": "videos/.../highlights-clip-002.mp4", "s3_url": "https://storage.example/clip-002.mp4?signature=...", "file_size": 2500000}
  ]
}

The completion webhook includes the same clip_files array. The main s3_url points to the first clip for compatibility; the job’s file_size is the sum of all clip sizes. The job completes only after every clip uploads. On failure or cancellation during upload, cleanup of partially uploaded clips is attempted; the job is not marked successfully delivered. Retries create a new job and preserve the requested ranges. Rules: 1–100 ranges, both bounds required as strings (seconds, MM:SS or HH:MM:SS), finite non-negative values and clip_end > clip_start. Do not combine clips with top-level clip_start/clip_end. This mode requires one on-demand video, not a playlist, show or explicit live recording, and does not support download_subtitles. Marketplace clipping restrictions still apply. Active live streams are also rejected when the URL is submitted without live options. Completed live replays are supported. Cancelling the job interrupts the current encoding and prevents the remaining clips from starting. Timestamp precision follows the existing clipping/encoding behavior. There is one billing finalization: the delivered volume is the sum of the clips, with the account’s usual source-video floor applied once, not once per clip. Quota and output-size limits apply to the combined volume. Source-duration limits continue to apply to the original video. See Billing.

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
  }'

Set max_duration explicitly to express the recording window you need. Source availability, account limits and worker timeouts can end the recording earlier.

Age-Restricted Videos

YouTube serves age-restricted videos only to a signed-in, age-verified account. Send the Netscape cookies.txt export of such an account in cookies, with a single YouTube video URL:

curl -X POST "https://api.tornadoapi.io/jobs" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg url 'https://www.youtube.com/watch?v=VIDEO_ID' \
        --rawfile cookies cookies.txt '{url: $url, cookies: $cookies}')"

Use a dedicated account and export from a private window. The Age-Restricted Videos reference covers the export steps, the accepted format and what happens when YouTube rejects the cookies.

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\", \"lowest\", \"2160\", \"1440\", \"1080\", \"720\", \"480\", \"360\", \"240\", \"144\"]"
}

Invalid Timestamps

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

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

API Reference

Jobs

Bulk

Metadata

Batch Operations

User

Overview

Re-encoding requires a paid account

Audio-Only Extraction

Audio-only request

MP3 Output

Audio Formats

Resolution Selection

Available Resolutions

Example

Video Clipping

Timestamp Formats

Examples

Several clips from one video

Live Stream Recording

Parameters

Basic Live Recording

Record from Start (VOD Mode)

Wait for Scheduled Stream

Age-Restricted Videos

Combining Options

Error Handling

Invalid Resolution

Invalid Timestamps

​Overview

​Re-encoding requires a paid account

​Audio-Only Extraction

​Audio-only request

​MP3 Output

​Audio Formats

​Resolution Selection

​Available Resolutions

​Example

​Video Clipping

​Timestamp Formats

​Examples

​Several clips from one video

​Live Stream Recording

​Parameters

​Basic Live Recording

​Record from Start (VOD Mode)

​Wait for Scheduled Stream

​Age-Restricted Videos

​Combining Options

​Error Handling

​Invalid Resolution

​Invalid Timestamps

Overview

Re-encoding requires a paid account

Audio-Only Extraction

Audio-only request

MP3 Output

Audio Formats

Resolution Selection

Available Resolutions

Example

Video Clipping

Timestamp Formats

Examples

Several clips from one video

Live Stream Recording

Parameters

Basic Live Recording

Record from Start (VOD Mode)

Wait for Scheduled Stream

Age-Restricted Videos

Combining Options

Error Handling

Invalid Resolution

Invalid Timestamps