YouTube Video Downloader API
One authenticated POST turns a public YouTube URL into a saved MP4 — quality selector from 144p to 720p, direct video link, and normalized metadata as clean JSON.
- One REST Endpoint
- Quality Selector
- Normalized Metadata
- Idempotent Billable Writes
- Predictable Error Codes
- Samples In Five Languages
Request examples
curl -X POST "https://api.agentbody.io/v1/youtube/video/download" \
-H "Authorization: Bearer <YOUR_AGENTBODY_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"quality":"144p","url":"YOUR_URL"}'Response examples
Documented responses from the OpenAPI specification.
Downloaded YouTube media link and normalized public video metadata.
{
"duration_seconds": 180,
"format": "mp4",
"quality": "720p",
"size_mb": 15.2,
"title": "Example Video",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"video_content_type": "video/mp4",
"video_id": "dQw4w9WgXcQ",
"video_url": "https://api.apify.com/v2/key-value-stores/example/records/dQw4w9WgXcQ.mp4"
}Features
Use the YouTube Video Downloader API for archiving pipelines, offline content systems, and media workflows — URL in, MP4 link out.
One REST Endpoint
Call POST /v1/youtube/video/download with a bearer API key and the public video URL. The API saves the MP4 and returns a direct video link — no headless browser, no yt-dlp maintenance, no proxy rotation.
Quality Selector
Pass the quality field with any of 144p, 240p, 360p, 480p, or 720p. Each request pins the exact output you want, and the response confirms the quality, format, and size actually delivered.
Normalized Metadata
Every response pairs the video_url with video_id, title, duration_seconds, format, quality, size_mb, and video_content_type — stable fields your pipeline can store without per-request parsing.
Idempotent Billable Writes
Video saves are metered operations. Send an Idempotency-Key header on retries so an interrupted response does not double-bill the same video — repeated identical requests with one key return the original result.
Predictable Error Codes
Handle failures with documented status codes: 400 for an invalid request, 401 for a missing or bad API key, 409 for idempotency conflicts, and 502/503/504 for temporary upstream issues — each maps to a distinct fix or retry action.
Samples In Five Languages
This page generates request examples in curl, JavaScript, Python, Java, and Go directly from the endpoint's OpenAPI definition — adopt the HTTP client your stack already uses.
How to use
Follow these steps to call the YouTube Video Downloader API: create a key, build the POST request, and process the returned MP4 link.
Create An API Key
Create an AgentBody account and generate an API key in the console. Keep the key in your server environment or an approved secret store and send it as a bearer token — never in browser code or client bundles.
Build The Request
Send POST /v1/youtube/video/download with the required url and an optional quality of 144p, 240p, 360p, 480p, or 720p. The generated examples show the exact request in curl, JavaScript, Python, Java, and Go.
Add An Idempotency Key
Attach an Idempotency-Key header to every download you might retry — timeouts, connection drops, worker restarts. Repeated identical requests with the same key return the original response without re-billing.
Keep The Key Server-Side
Call the endpoint from your backend, a serverless function, or a scheduled job. If end users trigger downloads, proxy through your own endpoint so the key and billing stay under your control.
Parse The JSON Response
Read the returned video_url, video_id, title, duration_seconds, format, quality, and size_mb. Store the link with its metadata, or hand the URL straight to your storage layer — the fields are stable across requests.
Handle Errors Correctly
Fix 400 responses by correcting the request, 401 by configuring a valid key, and follow the documented Idempotency-Key behavior on 409. Retry 502, 503, and 504 with backoff under the same key.
Frequently asked questions
What is the YouTube Video Downloader API?
An authenticated POST endpoint, /v1/youtube/video/download, that saves one public YouTube video as an MP4 and returns a direct video link with normalized metadata — video_id, title, duration, format, quality, and size — as structured JSON.
How does YouTube downloader API pricing work?
Each video save is a metered operation that runs on your account's credits. Pricing is governed by the gateway rather than fixed numbers on this page — check the console for current per-call costs, and use idempotency keys so retries never double-bill.
What qualities does the YouTube download API support?
The quality field accepts 144p, 240p, 360p, 480p, and 720p. The maximum this API offers is 720p — there is no 1080p or 4K setting. The response reports the quality actually delivered.
Can it replace a yt-dlp or scraper setup?
For public videos up to 720p, yes. Instead of maintaining yt-dlp updates, format negotiation, and proxy handling, you call one documented REST endpoint and receive a stable JSON payload with the file link.
Does the API download private or members-only videos?
No. The endpoint reads public videos only — private, members-only, and removed videos will not resolve, and no YouTube credentials are requested to work around the limit.
How do I handle API errors?
Correct the request body on 400, fix your bearer key on 401, and follow the documented Idempotency-Key behavior on 409. Treat 502, 503, and 504 as temporary upstream failures and retry with backoff under the same key.