YouTube Metadata API

A YouTube metadata API returns structured facts about a video — its title, duration, thumbnail, and available formats — without downloading anything. This guide shows how to read that data in one request with the Tunelio GET /info endpoint.

What the metadata endpoint returns

GET /info takes a single url parameter and returns the video title, duration (both in seconds and a human-readable string), the highest-resolution thumbnail, and a formats array describing every downloadable video and audio rendition with exact file sizes.

curl "https://tunelio.dev/info?url=https://youtu.be/dQw4w9WgXcQ" \
  -H "Authorization: Bearer tnl_your_api_key"

{
  "title": "Example Video",
  "duration_seconds": 213,
  "duration_str": "03:33",
  "thumbnail": "https://i.ytimg.com/vi_webp/…/maxresdefault.webp",
  "formats": [
    { "quality": "1080p", "file_size_str": "48.10 MB", "width": 1920, "height": 1080 },
    { "quality": "720p",  "file_size_str": "28.52 MB", "width": 1280, "height": 720 }
  ],
  "audioFormat": { "format": "mp3", "file_size_str": "3.29 MB" }
}

Common uses

• Show a video preview — title, thumbnail, and duration — before a user downloads.
• Let users pick a format by displaying each resolution and its exact size.
• Validate a URL and confirm a video exists before spending credits on a download.

Read it in Python

import os, requests

info = requests.get(
    "https://tunelio.dev/info",
    params={"url": "https://youtu.be/dQw4w9WgXcQ"},
    headers={"Authorization": f"Bearer {os.environ['TUNELIO_KEY']}"},
).json()

print(info["title"], info["duration_str"])
for f in info["formats"]:
    print(f["quality"], f["file_size_str"])

Validate a video before you download

GET /info is also the cheapest way to confirm a video exists and is downloadable before you spend credits on /create. If the URL is private, deleted, or geo-blocked, /info returns an error you can surface to the user immediately — no wasted download attempt. The duration_seconds field is handy here too, for rejecting livestreams or videos longer than your app allows.

Thumbnail and duration

The thumbnail field is the highest-resolution image YouTube exposes for the video, so you can render a preview card without a second request. duration_str is already formatted as HH:MM:SS (or MM:SS under an hour), while duration_seconds gives you the raw integer for your own formatting or filtering.

Cost

Each GET /info call costs 6 credits, and new accounts start with 100 free credits. Because /info reports exact file sizes, you can let users choose a format before you spend the 10 credits a GET /create download costs.

Next steps

See the full API documentation for the complete /info response schema and every field, or pair it with GET /create to turn the metadata you read into a direct download URL.