Skip to main content
POST
https://api.tornadoapi.io
/
jobs
Create Job
curl --request POST \
  --url https://api.tornadoapi.io/jobs \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "url": "<string>",
  "format": "<string>",
  "video_codec": "<string>",
  "audio_codec": "<string>",
  "audio_bitrate": "<string>",
  "video_quality": 123,
  "filename": "<string>",
  "folder": "<string>",
  "webhook_url": "<string>",
  "audio_only": true,
  "download_subtitles": true,
  "download_thumbnail": true,
  "quality_preset": "<string>",
  "max_resolution": "<string>",
  "clip_start": "<string>",
  "clip_end": "<string>",
  "live_recording": true,
  "live_from_start": true,
  "max_duration": 123,
  "wait_for_video": true,
  "enable_progress_webhook": true
}
'
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Overview

Creates a new download job. For single videos, returns a job_id. For Spotify shows, automatically creates a batch and returns a batch_id with all episode job IDs.

​
Header Parameters

​
x-api-key
string
required
Your API key for authentication

​
Request

​
url
string
required
The video or show URL to download
​
format
string
Output container format: mp4, mkv, webm, mov. Default: mp4
​
video_codec
string
Video codec: copy (no re-encode), h264, h265, vp9. Default: copy
​
audio_codec
string
Audio codec: copy (no re-encode), aac, opus, mp3. Default: copy with automatic fallback to aac if incompatible
​
audio_bitrate
string
Audio bitrate when transcoding: 64k, 128k, 192k, 256k, 320k. Default: 192k
​
video_quality
integer
Video quality CRF (0-51, lower = better quality). Only used when video_codec is not copy. Default: 23
​
filename
string
Custom filename (without extension). Will be sanitized.
​
folder
string
S3 folder prefix for organizing files. Cannot contain .. or start with /.
​
webhook_url
string
URL to receive completion notification via POST request.
​
audio_only
boolean
default:"false"
Extract audio track only. Outputs mp3/aac file instead of video.
​
download_subtitles
boolean
default:"false"
Download subtitles if available. Returns subtitle URL in job response.
​
download_thumbnail
boolean
default:"false"
Download video thumbnail. Returns thumbnail URL in job response.
​
quality_preset
string
Quality preset that overrides video_quality. Options: highest, high, medium, low, lowest.
​
max_resolution
string
Maximum video resolution. Options: best (default), 2160 (4K), 1440, 1080, 720, 480, 360.
​
clip_start
string
Start timestamp for video clipping. Format: HH:MM:SS or seconds (e.g., 00:01:30 or 90).
​
clip_end
string
End timestamp for video clipping. Format: HH:MM:SS or seconds (e.g., 00:05:00 or 300).
​
live_recording
boolean
default:"false"
Enable live stream recording mode. Auto-detected for live URLs.
​
live_from_start
boolean
default:"false"
For live streams: record from the beginning (VOD mode) instead of the live point.
​
max_duration
integer
Maximum recording duration in seconds. Recommended for live streams as a safety cap. Example: 7200 for 2 hours.
​
wait_for_video
boolean
default:"false"
Wait for scheduled/upcoming streams to start before downloading.
​
enable_progress_webhook
boolean
default:"false"
Enable progress webhooks during processing. Sends updates at each stage: downloading, muxing, uploading.

​
Single Job Response

​
job_id
string
UUID of the created job
Response
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Batch Response (Spotify Shows)

When the URL is a Spotify show, a batch is created automatically:
​
batch_id
string
UUID of the batch job
​
total_episodes
integer
Number of episodes in the show
​
episode_jobs
array
List of job IDs for each episode
Response
{
  "batch_id": "550e8400-e29b-41d4-a716-446655440001",
  "total_episodes": 142,
  "episode_jobs": [
    "job-uuid-1",
    "job-uuid-2",
    "job-uuid-3"
  ]
}

​
Examples

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

​
Success Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Error Responses

{
  "error": "Folder name too long (max 200 characters)"
}