Submit a download - API Documentation

Authorization

bearerAuth

AuthorizationBearer <token>

API key issued from the dashboard, sent as Authorization: Bearer YOUR_API_KEY.

In: header

Request Body

application/json

Download parameters.

TypeScript Definitions

Use the request body type in TypeScript.

url*string

YouTube video URL. Supported patterns:

https://youtube.com/watch?v=ID
https://youtu.be/ID
https://youtube.com/live/ID

format?string

Target format. Defaults to mp3. Higher video qualities may be capped down for very long videos to fit your plan's per-file size limit.

Default"mp3"

Value in"1080" | "720" | "480" | "360" | "240" | "144" | "mp3"

startTime?integer

Trim start in seconds (inclusive). Must be in [0, duration). Omit to start from the beginning.

Range0 <= value

endTime?integer

Trim end in seconds (exclusive). Must be in (0, duration] and greater than startTime. Omit to go to the end.

Range1 <= value

language?string

Preferred audio track language as a BCP-47 tag (e.g. en, en-US, th). Use POST /info to discover what's available for a given video — audio[].language lists the languages and audio[].type indicates original vs. dubbed.

Fallback chain: if the requested language isn't available on the video, the download falls back to (1) any track whose language tag starts with the requested value (e.g. en matches en-US), then to (2) the video's original/default audio. Omit this field to always use the original audio.

Match^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$

Response Body

`application/json`

curl -X POST "https://youtube-download-api.org/api/v2/download" \  -H "Content-Type: application/json" \  -d '{    "url": "https://youtu.be/dQw4w9WgXcQ",    "format": "mp3"  }'

{
  "jobId": "69cfc45e8a3b4d2f9c1e0a7b",
  "title": "Rick Astley - Never Gonna Give You Up",
  "duration": 213,
  "status": "IN_QUEUE",
  "message": "Download job enqueued. Poll GET /api/v2/download/{jobId} for status."
}

{
  "error": "Missing required field: url"
}

{
  "error": "Missing API key. Provide it as 'Bearer YOUR_API_KEY'"
}

{
  "error": "Download limit reached",
  "downloadsUsed": 25,
  "downloadsAllowance": 25
}

{
  "error": "Failed to enqueue download job"
}

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

500application/json

Example missing-url

Example bad-format

Example live-in-progress

Example missing

Example invalid

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`