YouTube Metadata API

Автор Команда Tunelio·Опубликовано 13 июн. 2026

YouTube metadata API возвращает структурированные факты о видео — название, длительность, превью и доступные форматы — ничего не скачивая. В этом руководстве показано, как прочитать эти данные одним запросом к endpoint Tunelio GET /info.

Что возвращает endpoint метаданных

GET /info принимает единственный параметр url и возвращает название видео, длительность (в секундах и в читаемом виде), превью в максимальном разрешении и массив formats, описывающий каждую скачиваемую видео- и аудиоверсию с точными размерами файлов.

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" }
}

Типичные сценарии

• Показать превью видео — название, картинку и длительность — до того, как пользователь скачает.
• Дать пользователю выбрать формат, показав каждое разрешение и его точный размер.
• Проверить ссылку и убедиться, что видео существует, прежде чем тратить кредиты на загрузку.

Чтение в 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"])

Проверка видео перед загрузкой

GET /info — ещё и самый дешёвый способ убедиться, что видео существует и доступно для скачивания, прежде чем тратить кредиты на /create. Если ссылка приватная, удалённая или гео-заблокированная, /info вернёт ошибку, которую можно сразу показать пользователю — без напрасной попытки загрузки. Поле duration_seconds здесь тоже полезно: им удобно отсекать трансляции или видео длиннее, чем допускает приложение.

Превью и длительность

Поле thumbnail — изображение в максимальном разрешении, которое YouTube отдаёт для видео, так что карточку-превью можно отрисовать без второго запроса. duration_str уже отформатирован как HH:MM:SS (или MM:SS, если меньше часа), а duration_seconds даёт целое число для собственного форматирования или фильтрации.

Стоимость

Каждый вызов GET /info стоит 6 кредитов, а новые аккаунты начинают со 100 бесплатных. Поскольку /info сообщает точные размеры файлов, пользователь может выбрать формат до того, как вы потратите 10 кредитов на загрузку через GET /create.

Дальше

Смотрите полную документацию API с полной схемой ответа /info и всеми полями — или соедините его с GET /create, чтобы превратить прочитанные метаданные в прямую ссылку на скачивание.