Skip to main content
POST
/
jobs
/
bulk
Bulk Create Jobs
curl --request POST \
  --url https://api.example.com/jobs/bulk \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "jobs": [
    {}
  ],
  "jobs[].url": "<string>",
  "jobs[].filename": "<string>",
  "folder": "<string>",
  "format": "<string>",
  "video_codec": "<string>",
  "audio_codec": "<string>",
  "audio_bitrate": "<string>",
  "video_quality": 123,
  "audio_only": true,
  "download_subtitles": true,
  "download_thumbnail": true,
  "quality_preset": "<string>"
}
'
{
  "batch_id": "550e8400-e29b-41d4-a716-446655440001",
  "total_jobs": 3,
  "job_ids": [
    "660f9511-f30c-52e5-b827-557766551111",
    "660f9511-f30c-52e5-b827-557766551112",
    "660f9511-f30c-52e5-b827-557766551113"
  ]
}

​
Overview

Create up to 100 download jobs in a single API request. All jobs share the same encoding options but can have individual filenames. Returns a batch ID for tracking all jobs together.

​
Header Parameters

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

​
Request

​
jobs
array
required
Array of job items (max 100)

​
Job Item

​
jobs[].url
string
required
Video URL to download
​
jobs[].filename
string
Custom filename for this specific job

​
Shared Options

​
folder
string
S3 folder prefix for all jobs
​
format
string
Output format for all jobs: mp4, mkv, webm, mov
​
video_codec
string
Video codec for all jobs: copy, h264, h265, vp9
​
audio_codec
string
Audio codec for all jobs: copy, aac, opus, mp3
​
audio_bitrate
string
Audio bitrate for all jobs: 64k, 128k, 192k, 256k, 320k
​
video_quality
integer
Video quality CRF for all jobs (0-51)
​
audio_only
boolean
default:"false"
Extract audio only for all jobs
​
download_subtitles
boolean
default:"false"
Download subtitles for all jobs
​
download_thumbnail
boolean
default:"false"
Download thumbnails for all jobs
​
quality_preset
string
Quality preset for all jobs: highest, high, medium, low, lowest

​
Response

​
batch_id
string
Batch ID for tracking all jobs
​
total_jobs
integer
Number of jobs created
​
job_ids
array
List of individual job IDs

​
Examples

curl -X POST "https://tornado.velys.software/jobs/bulk" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jobs": [
      {"url": "https://youtube.com/watch?v=video1", "filename": "my-first-video"},
      {"url": "https://youtube.com/watch?v=video2", "filename": "my-second-video"},
      {"url": "https://youtube.com/watch?v=video3"}
    ],
    "folder": "my-downloads",
    "format": "mp4"
  }'

​
Success Response

{
  "batch_id": "550e8400-e29b-41d4-a716-446655440001",
  "total_jobs": 3,
  "job_ids": [
    "660f9511-f30c-52e5-b827-557766551111",
    "660f9511-f30c-52e5-b827-557766551112",
    "660f9511-f30c-52e5-b827-557766551113"
  ]
}

​
Error Responses

{
  "error": "No jobs provided"
}

​
Notes

  • Maximum 100 jobs per bulk request
  • All jobs share the same encoding options and folder
  • Each job can have a unique filename
  • Webhooks are not supported in bulk requests (use individual job creation for webhooks)
  • Use /jobs/{id} to poll individual job status
  • The batch_id is for reference only - jobs are processed independently