Skip to main content
POST
/
jobs
Create Job
curl --request POST \
  --url https://api.example.com/jobs \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "format": "<string>",
  "video_codec": "<string>",
  "audio_codec": "<string>",
  "audio_bitrate": "<string>",
  "video_quality": 123,
  "filename": "<string>",
  "folder": "<string>",
  "webhook_url": "<string>"
}
'
{
  "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.

​
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.

​
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://tornado.velys.software/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)"
}