API Reference

Extract the best cover image from any URL. Supports YouTube, Bilibili, Twitter, Medium, Reddit and any page with Open Graph or oEmbed metadata.

OpenAPI Spec(JSON)

Base URL

https://youtube.coverimage.dev

Authentication

No authentication required. The API is open and free to use.

GET /api/resolve

Resolve the best cover image for a given URL using query parameters. Ideal for quick tests and simple integrations.

Query Parameters

Param	Type	Default	Description
url	string	required	The page URL to extract cover image from

curl Examples

YouTube video

curl "https://youtube.coverimage.dev/api/resolve?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Any webpage (Open Graph)

curl "https://youtube.coverimage.dev/api/resolve?url=https://github.com/vercel/next.js"

With jq for pretty print

curl -s "https://youtube.coverimage.dev/api/resolve?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" | jq .

POST /api/resolve

Resolve the best cover image using a JSON request body. Recommended for programmatic use.

Request Body

Field	Type	Default	Description
url	string	required	The page URL to extract cover image from

curl Examples

Basic request

curl -X POST https://youtube.coverimage.dev/api/resolve \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

Extract only the image URL

curl -s -X POST https://youtube.coverimage.dev/api/resolve \
  -H "Content-Type: application/json" \
  -d '{"url": "https://medium.com/@example/my-article"}' \
  | jq -r '.best.url'

Response Format

Both GET and POST return the same JSON response structure.

Response Fields

Field	Type	Description
request_id	string	—	Unique request identifier
canonical	object	—	{ platform, resource_type, resource_id, canonical_url }
best	ImageCandidate	—	Highest-scored candidate image
candidates	ImageCandidate[]	—	All candidates sorted by score
cache	object	—	{ hit: boolean, ttl_seconds: number }
trace	object	—	Pipeline execution trace (steps, timings)
meta	object?	—	Page metadata (title, author, etc.)
warnings	array?	—	Non-fatal issues encountered
errors	array?	—	Errors encountered during resolve

ImageCandidate Object

Field	Type	Description
url	string	—	Direct image URL
width	number\|null	—	Image width in pixels
height	number\|null	—	Image height in pixels
format	enum	—	"jpg" \| "png" \| "webp" \| "avif" \| "gif" \| "unknown"
quality_tier	enum	—	"max" \| "high" \| "medium" \| "low" \| "unknown"
score	number\|null	—	Composite score (tier bonus + pixel bonus)
source_method	enum	—	"rule" \| "api" \| "og" \| "oembed" \| ...
availability	object	—	{ status: "ok"\|"missing"\|"blocked"\|"error", http_status? }

Example Response

{
  "request_id": "mme7othw-i1eau49ph",
  "canonical": {
    "platform": "youtube",
    "resource_type": "video",
    "resource_id": { "videoId": "dQw4w9WgXcQ" },
    "canonical_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  },
  "best": {
    "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
    "width": 1280,
    "height": 720,
    "format": "jpg",
    "quality_tier": "max",
    "score": 129.8,
    "source_method": "rule",
    "availability": { "status": "ok", "http_status": 200 }
  },
  "candidates": [ "...5 candidates from maxres to default..." ],
  "cache": { "hit": false, "ttl_seconds": 86400 },
  "trace": { "timings": { "total_ms": 789 } }
}

Error Codes

HTTP	Code	Description
400	MISSING_URL	The url parameter is missing or empty
400	INVALID_JSON	POST request body is not valid JSON
502	RESOLVE_ERROR	Failed to fetch or parse the target page

YouTube Quality Tiers

For YouTube videos, the API probes 5 thumbnail quality tiers and returns the best available:

Tier	URL Pattern	Typical Size
max	i.ytimg.com/vi/ID/maxresdefault.jpg	1280x720
high	i.ytimg.com/vi/ID/sddefault.jpg	640x480
medium	i.ytimg.com/vi/ID/hqdefault.jpg	480x360
low	i.ytimg.com/vi/ID/mqdefault.jpg	320x180
low	i.ytimg.com/vi/ID/default.jpg	120x90

Playground

Try the API directly from your browser. Choose GET or POST, enter a URL, and click Send. The corresponding curl command is shown below.

curl "https://youtube.coverimage.dev/api/resolve?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ"