Skip to main content
POST
/
dca
/
trigger_hp
Trigger a video download job
curl --request POST \
  --url https://api.brightdata.com/dca/trigger_hp \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "format": "all_audio_tracks+video",
    "captions": true,
    "captions_format": "vtt",
    "quality_filter": [
      720,
      1080,
      1440
    ],
    "quality_priority": "lowest",
    "time_ranges": [
      {
        "start": 30,
        "end": 75
      },
      {
        "start": 180,
        "end": 270
      }
    ],
    "merge_ranges": false,
    "thumbnail": true,
    "storyboards": true
  }
]
'
{
  "success": true,
  "inputs": 1,
  "job_id": "hp_mn1l61rn1p94ynijur"
}
The Video Downloader API is not enabled by default. Contact support@brightdata.com to enable it for your account.
A delivery destination is required for every request. Configure a delivery destination before sending your first request. See Delivery options.

​
Input fields

The request body is a JSON array. Each object in the array is a separate download job.
​
url
string
required
The full URL of the video to download. Supported platforms: YouTube, Vimeo, TikTok, Bilibili.
​
format
string
default:"full"
Specifies what content type to download.
ValueDescription
fullDownloads the video with the default audio track
video_onlyDownloads the video stream without audio
audio_onlyDownloads the default audio track only
all_audio_tracksDownloads all available audio tracks (for example, multiple languages) without video
all_audio_tracks+videoDownloads the video together with all available audio tracks
noneSkips media download. Use when you only need captions, thumbnails, or storyboards
​
captions
boolean
default:"false"
Whether to download available captions or subtitles for the video.
​
captions_format
string
default:"vtt"
The file format for downloaded captions. Only applies when captions is true.
ValueDescription
vttWebVTT format
srtSubRip format
json3JSON format
​
quality_filter
integer[]
default:"[]"
An array of accepted video quality resolutions, expressed as vertical pixel counts. The download proceeds only if at least one of the specified resolutions is available.Common values: 360, 480, 720, 1080, 1440, 2160
​
quality_priority
string
default:"highest"
When multiple resolutions from quality_filter are available, determines which one is selected.
ValueDescription
highestSelects the highest available resolution match
lowestSelects the lowest available resolution match
​
time_ranges
object[]
default:"[]"
An array of time range objects that limits the download to specific portions of the video. Start and end values are in seconds. If omitted, the full video is downloaded.Example: [{"start": 0, "end": 10}, {"start": 30, "end": 75}]
​
merge_ranges
boolean
default:"true"
Controls whether multiple time_ranges are delivered as one merged file or as separate files. Only applies when time_ranges contains more than one range.
ValueDescription
trueAll ranges are merged into a single continuous file
falseEach range is delivered as a separate file
​
thumbnail
boolean
default:"false"
Whether to include the video’s thumbnail image in the results.
​
storyboards
boolean
default:"false"
Whether to include the video’s storyboard images (sprite sheets used for timeline preview scrubbing) in the results.
​
extra_path
string
A custom path for file upload. Overrides the path configured in your delivery settings. Supports template variables: {{datetime}}, {{video_id}}, {{job}}.Example: "my-videos/{{video_id}}/{{datetime}}"
​
filename
string
A custom filename for uploaded files. The value is used as the base name across all output files (e.g. <filename>.mp4, <filename>.metadata.json, <filename>.sub.0). Supports template variables: {{datetime}}, {{video_id}}, {{job}}.Example: "{{video_id}}_{{datetime}}"

Authorizations

​
Authorization
string
header
required

Your Bright Data API token. Find it in the Bright Data Control Panel.

Query Parameters

​
collector
string
required

Your Video Downloader collector ID. This is a fixed value assigned when the feature is enabled on your account.

Example:

"YOUR_COLLECTOR_ID"

Body

application/json

A JSON array of download job objects. Each object represents one video download job. Multiple jobs can be submitted in a single request.

Minimum array length: 1
​
url
string
required

The full URL of the video to download. Supported platforms: YouTube, Vimeo, TikTok, Bilibili.

Example:

"https://www.youtube.com/watch?v=dQw4w9WgXcQ"

​
format
enum<string>
default:full

Specifies what content type to download.

Available options:
full,
video_only,
audio_only,
all_audio_tracks,
all_audio_tracks+video,
none
​
captions
boolean
default:false

Whether to download available captions or subtitles for the video.

​
captions_format
enum<string>
default:vtt

The file format for downloaded captions. Only applies when captions is true. Supported formats: vtt, srt, json3.

Available options:
vtt,
srt,
json3
​
quality_filter
integer[]

An array of accepted video quality resolutions, expressed as vertical pixel counts. The download proceeds only if at least one of the specified resolutions is available. Common values: 360, 480, 720, 1080, 1440, 2160.

Example:
[720, 1080, 1440]
​
quality_priority
enum<string>
default:highest

When multiple resolutions from quality_filter are available, determines which one is selected.

Available options:
highest,
lowest
​
time_ranges
object[]

An array of time range objects that limits the download to specific portions of the video. Start and end values are in seconds. If omitted, the full video is downloaded.

Example:
[
  { "start": 0, "end": 10 },
  { "start": 30, "end": 75 }
]
​
merge_ranges
boolean
default:true

Controls whether multiple time_ranges are delivered as one merged file or as separate files. Only applies when time_ranges contains more than one range.

​
thumbnail
boolean
default:false

Whether to include the video's thumbnail image in the results.

​
storyboards
boolean
default:false

Whether to include the video's storyboard images (sprite sheets used for timeline preview scrubbing) in the results.

Response

Job accepted successfully.

​
success
boolean

true when the job was accepted.

​
inputs
integer

Number of download jobs submitted.

​
job_id
string

Unique identifier for the submitted job.