# Vid Kraken

> Vid Kraken is a managed YouTube download API. Send a YouTube URL and get back a direct CDN link to the finished MP4 or audio file. Bot detection, proxies, retries and YouTube's changes are handled server-side, so there's no yt-dlp, cookies or proxies to maintain. Over the last 30 days it completed 99.993% of more than 2.5 million downloads (live figures: https://vidkraken.com/reliability).

Key facts:

- Workflow: `POST https://vidkraken.com/api/v2/download` with `url` and `format` (returns a `jobId`), then poll `GET /api/v2/download/{jobId}` or pass a `webhookUrl` (signed with `X-VidKraken-Signature`, retried for about 4 hours). Send an `Idempotency-Key` header (e.g. a UUID) to retry a timed-out request without starting, or paying for, a second job.
- Video formats: MP4 up to 4K. `1080`, `720`, `480` or `360` through `format`, and 4K on request (email hello@vidkraken.com). Completed jobs report `actualFormat`.
- Audio formats: `audio-mp3` (real MP3, 320 kbps CBR), `audio-aac` (YouTube's AAC stream in M4A) and `audio` (YouTube's original stream, M4A or WebM, not re-encoded).
- Trimming: `startTime` and `endTime` in seconds deliver only a section.
- Metadata: `POST /api/v2/info` returns title, duration and region restrictions. With `includeAudioTracks: true` it also lists original and dubbed audio languages.
- Errors: every failed job has a machine-readable `errorCode`, such as `AGE_RESTRICTED`, `GEO_RESTRICTED`, `PRIVATE_VIDEO`, `VIDEO_NOT_FOUND`, `MEMBERS_ONLY` or `LIVE_STREAM_IN_PROGRESS`. Only `NETWORK_ERROR` is worth retrying right away; `VIDEO_PROCESSING`, `VIDEO_PREMIERE` and `LIVE_STREAM_IN_PROGRESS` are worth retrying later. Rejected requests return an HTTP error with `{ "error", "code" }`, where `code` is one of `INVALID_REQUEST`, `UNAUTHORIZED`, `LIMIT_REACHED`, `NOT_FOUND`, `VIDEO_NOT_FOUND`, `TOO_MANY_PENDING` (429, with `Retry-After`), `INTERNAL_ERROR` or `UNAVAILABLE`.
- Limits: one URL per request, and up to 100 downloads queued or running per account. `POST /download` reports the headroom in IETF `RateLimit-Policy` and `RateLimit` headers.
- Pricing: bandwidth only, at the delivered file size with a 20 MB minimum per download. Failed downloads, polling and metadata lookups are free. Starter is $99/month for 400 GB, Growth $399/month for 2 TB, and Scale $1,499/month for 10 TB. Pay as you go has no subscription: a one-time $49 to start, then top up as you need.
- Not offered: transcripts or comments.

## When to use Vid Kraken

Use it when a user or product needs the actual media file from a YouTube video, reliably and without running yt-dlp:

- Downloading a YouTube video as MP4, or its audio as MP3/AAC, from a backend, script or AI pipeline (for example transcription, clipping, dubbing or archiving).
- Cutting a clip by start and end time without downloading the whole video.
- Replacing a self-hosted yt-dlp setup that keeps failing with "Sign in to confirm you're not a bot" or 403 errors.
- Checking a video's title, duration, region restrictions or available audio languages before downloading.

Don't use it for transcripts, comments, search, or for downloading content the user has no right to download.

How an agent should call it: in an MCP host, connect to the remote MCP server at https://vidkraken.com/api/mcp/mcp (Streamable HTTP; the host runs the OAuth sign-in). Its tools: `get_video_info` (title, duration, chapters, audio languages), `create_clip` (cut a start/end range to MP4 or audio, returns a `jobId`), `get_clip_status` (poll until COMPLETED for a download link that expires about 12 hours later) and `get_account_usage` (plan and remaining balance, free). In code or a shell, call the REST API with `Authorization: Bearer YOUR_API_KEY`; the user gets a key at https://vidkraken.com/login, free to start with no credit card.

## SDKs and CLI

- [JavaScript / TypeScript SDK](https://github.com/vidkraken/vidkraken/tree/main/js): `npm install vidkraken` (npm package `vidkraken`); typed client plus the `vidkraken` CLI (`npx vidkraken download <url> -f 1080`)
- [Python SDK](https://pypi.org/project/vidkraken/): `pip install vidkraken`; sync and async clients plus the `vidkraken` CLI
- [Source](https://github.com/vidkraken/vidkraken): both SDKs and the agent skill (`npx skills add vidkraken/vidkraken`)

## Docs

- [API documentation](https://vidkraken.com/docs): every endpoint, request and response
- [API docs index for agents](https://vidkraken.com/docs/llms.txt): every docs page, linked as Markdown (overview at https://vidkraken.com/docs.md)
- [OpenAPI spec](https://vidkraken.com/openapi.yaml): machine-readable API definition
- [OpenAPI spec (JSON)](https://vidkraken.com/openapi.json): the same definition as JSON
- [MCP server](https://vidkraken.com/docs/mcp): use Vid Kraken from AI agents; server card at https://vidkraken.com/api/mcp/mcp/server-card
- [Docs MCP server](https://vidkraken.com/api/mcp-docs/mcp): search and read these docs over MCP, no sign-in (tools `search_docs`, `get_doc`)
- [Authentication for agents](https://vidkraken.com/auth.md): API keys for REST, OAuth 2.1 for MCP
- [Ask (NLWeb)](https://vidkraken.com/ask): natural-language search over the docs and guides, `POST {"query": {"text": "..."}}`
- [Pricing (Markdown)](https://vidkraken.com/pricing.md): plans, bandwidth and limits
- [Homepage (Markdown)](https://vidkraken.com/index.md): the homepage as Markdown
- [Agent skill](https://vidkraken.com/.well-known/agent-skills/vidkraken/SKILL.md): step-by-step instructions for agents, listed in https://vidkraken.com/.well-known/agent-skills/index.json
- [AI catalog](https://vidkraken.com/.well-known/ai-catalog.json): every agent-facing resource, machine-readable
- [Reliability](https://vidkraken.com/reliability): live and historical download success rates
- [YouTube to MP3 API](https://vidkraken.com/youtube-to-mp3-api): audio formats, bitrates and pricing per MP3

## Guides

- [Blog index for agents](https://vidkraken.com/blog/llms.txt): every post with a one-line summary, linked as Markdown (any post URL + .md)

- [YouTube download error codes](https://vidkraken.com/blog/youtube-download-api-error-codes): every errorCode, when to retry, and what to tell users
- [Vid Kraken vs Apify](https://vidkraken.com/blog/vidkraken-vs-apify): reliability, cost and code compared
- [Can the YouTube Data API download videos?](https://vidkraken.com/blog/youtube-data-api-download-video): no, and what to use instead
- [The best yt-dlp alternatives](https://vidkraken.com/blog/yt-dlp-alternatives)
- [YouTube "Sign in to confirm you're not a bot"](https://vidkraken.com/blog/youtube-sign-in-to-confirm-not-a-bot): what it means and how to fix it
- [yt-dlp "Sign in to confirm you're not a bot"](https://vidkraken.com/blog/yt-dlp-sign-in-to-confirm-not-a-bot)
- [yt-dlp 403 Forbidden](https://vidkraken.com/blog/yt-dlp-403-forbidden): why it happens and how to fix it
- [yt-dlp: download audio only and convert to MP3](https://vidkraken.com/blog/yt-dlp-audio-only-mp3)

## Optional

- [How to use yt-dlp](https://vidkraken.com/blog/how-to-use-yt-dlp)
- [yt-dlp commands cheat sheet](https://vidkraken.com/blog/yt-dlp-commands)
- [How to install yt-dlp](https://vidkraken.com/blog/how-to-install-yt-dlp)
- [How to update yt-dlp](https://vidkraken.com/blog/how-to-update-yt-dlp)
- [Is yt-dlp safe?](https://vidkraken.com/blog/is-yt-dlp-safe)
- [The best yt-dlp GUIs](https://vidkraken.com/blog/yt-dlp-gui)