YouTube Thumbnail Downloader API
One authenticated POST returns the direct CDN image link for any public YouTube video thumbnail — quality selector with automatic fallback, clean JSON.
- One REST Endpoint
- Quality With Fallback
- Every Link Shape
- Stable Response Fields
- Idempotent Billable Writes
- Predictable Error Codes
Request examples
curl -X POST "https://api.agentbody.io/v1/youtube/thumbnail/download" \
-H "Authorization: Bearer <YOUR_AGENTBODY_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"quality":"maxresdefault","url":"YOUR_URL"}'Response examples
Documented responses from the OpenAPI specification.
Direct thumbnail image link and normalized public video metadata.
{
"quality": "maxresdefault",
"thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"video_id": "dQw4w9WgXcQ"
}Features
Use the YouTube Thumbnail API for content research pipelines, design tooling, and media libraries — video URL in, CDN image link out.
One REST Endpoint
Call POST /v1/youtube/thumbnail/download with a bearer API key and the video URL. The API resolves the video and returns its thumbnail's direct CDN link — no screenshot tooling, no page scraping.
Quality With Fallback
Pass quality as maxresdefault, sddefault, hqdefault, or mqdefault. When the requested tier does not exist, the operation falls back automatically to the best available one and reports what it served.
Every Link Shape
Watch URLs, Shorts links, live URLs, embed links, and youtu.be links all resolve. Integrations accept whatever users paste without a normalization step.
Stable Response Fields
Every response carries thumbnail_url, quality, video_id, and the canonical video url — fields your pipeline stores and joins against without per-request parsing.
Idempotent Billable Writes
Thumbnail fetches are metered. 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
Documented status codes: 400 invalid request, 401 missing or bad key, 409 idempotency conflict, 502/503/504 temporary upstream issues — each maps to a distinct fix or retry action.
How to use
Follow these steps to call the YouTube Thumbnail API: create a key, build the POST request, and process the returned CDN link.
Create An API Key
Create an AgentBody account and generate an API key in the console. Keep the key server-side and send it as a bearer token — never in browser code or client bundles.
Build The Request
Send POST /v1/youtube/thumbnail/download with the required url and an optional quality. 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 fetch you might retry. 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 fetches, proxy through your own endpoint so the key and billing stay under your control.
Parse The JSON Response
Read the returned thumbnail_url, quality, video_id, and url. Store the CDN link with the video it belongs to — the fields are stable across requests.
Handle Errors Correctly
Fix 400 by correcting the request, 401 by configuring a valid key, and follow the documented Idempotency-Key behavior on 409. Retry 502/503/504 with backoff under the same key.
Frequently asked questions
What is the YouTube Thumbnail Downloader API?
An authenticated POST endpoint, /v1/youtube/thumbnail/download, that resolves a public YouTube video from any link shape and returns its thumbnail as a direct CDN image URL — with a quality selector (maxresdefault down to mqdefault) and automatic fallback when a tier is unavailable.
What resolutions does the thumbnail API support?
maxresdefault, sddefault, hqdefault, and mqdefault. The default request asks for max; when that tier does not exist for the video, the API falls back to the best available quality and reports which one it served.
How does pricing work?
Each thumbnail fetch is a metered operation on your account's credits. Pricing is gateway-governed rather than fixed on this page — check the console, and use idempotency keys so retries never double-bill.
Which URL formats does the API accept?
Watch URLs, Shorts links, live URLs, embed links, and youtu.be short links — the endpoint detects the video from whatever link shape arrives.
Can I download YouTube thumbnails by link through the API?
Yes — POST the video link (watch, Shorts, live, embed, or youtu.be) and the response returns the thumbnail_url, quality, video_id, and canonical video URL as JSON. One request per link; batch pipelines simply iterate.
What does the thumbnail API cost?
Each fetch is a metered operation on your account's credits. Pricing is gateway-governed — check the console for current per-call costs. Idempotency keys keep retries free of double-billing.
Does it work for private or unlisted videos?
No. The endpoint reads public videos only — private, unlisted-when-hidden, and removed content will not resolve, and no YouTube credentials are requested.
How do I handle API errors?
Correct the request on 400, fix the 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.