Submit a download

For AI agents: docs index at /docs/llms.txt; any page as Markdown by adding .md to its URL.

Queue a YouTube video for download. Returns a jobId that you poll on GET /download/{jobId} until status is COMPLETED (or FAILED).

Prefer push over polling? Pass a webhookUrl and we POST the final status to it instead — the body is byte-for-byte the GET /download/{jobId} response. See the download.finished webhook below for headers, signature verification and retries.

The actually-delivered format is reported as actualFormat on the completed status response.

Cost: bandwidth at the actual file size delivered (20 MB minimum), charged when the background job completes — submitting the job is free. There is no per-download fee. Failures are not charged.

Authorization

Bearer token. API key issued from the dashboard, sent as Authorization: Bearer YOUR_API_KEY. Get a key at https://vidkraken.com/login.

Parameters

Idempotency-Key (header, string)

Optional. A unique string (e.g. a UUID), up to 255 visible ASCII characters. Retrying with the same key and body within 24 hours returns the original response instead of creating a second job.

Example: 4f1c9a2e-8d3b-4c7a-9f0e-2b6d5a1c3e7f.

Request Body

application/json

Download parameters.

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

Default"audio"

Value in"1080" | "720" | "480" | "360" | "audio" | "audio-aac" | "audio-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 with includeAudioTracks: true 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})*$

webhookUrl?string

Optional. A public https:// (or http://) URL we POST the job's final status to once it reaches COMPLETED or FAILED. The body is identical to the GET /download/{jobId} response, so one handler can serve both. Requests are signed with your API key and retried with exponential backoff for up to 10 attempts (~4 hours); see the download.finished webhook for details.

Loopback, private-network and single-label hostnames (e.g. localhost, 10.x, 192.168.x, intranet) are rejected with 400. Redirects are not followed — respond 2xx directly.

Formaturi

Lengthlength <= 2048

Response Body

`application/json`

curl -X POST "https://vidkraken.com/api/v2/download" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{"url":"https://youtu.be/dQw4w9WgXcQ","format":"audio"}'

{
  "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",
  "code": "INVALID_REQUEST"
}

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

{
  "error": "Credit limit reached",
  "code": "LIMIT_REACHED"
}

{
  "error": "Video not found. Check the URL — the video may be private, deleted, or the id may be wrong.",
  "code": "VIDEO_NOT_FOUND"
}

{
  "error": "A request with this Idempotency-Key is still being processed. Retry shortly.",
  "code": "IDEMPOTENCY_CONFLICT"
}

{
  "error": "This Idempotency-Key was already used with a different request body. Use a new key.",
  "code": "IDEMPOTENCY_KEY_REUSED"
}

{
  "error": "Too many pending downloads (100). Wait for some of your jobs to finish before submitting more (limit: 100 queued or in progress).",
  "code": "TOO_MANY_PENDING"
}

{
  "error": "Failed to enqueue download job",
  "code": "INTERNAL_ERROR"
}

{
  "error": "The download could not be queued. Please try again in a minute.",
  "code": "UNAVAILABLE"
}

Submit a download

Authorization

Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

503application/json

Example missing-url

Example bad-format

Example live-in-progress

Example too-long

Example missing

Example invalid

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`