YouTube 元数据 API

YouTube 元数据 API 返回关于视频的结构化信息——它的标题、时长、缩略图和可用格式——而不下载任何内容。本指南展示如何用 Tunelio GET /info 端点在一次请求中读取这些数据。

元数据端点返回什么

GET /info 只接收一个 url 参数，返回视频的 title、duration（同时给出秒数和便于阅读的字符串）、最高分辨率的 thumbnail，以及一个 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" }
}

常见用途

• 在用户下载之前展示视频预览——title、thumbnail 和 duration。
• 展示每种分辨率及其精确大小，让用户自行选择格式。
• 在为下载花费额度之前，先验证 URL 并确认视频确实存在。

用 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 花费额度之前，确认视频存在且可下载。如果 URL 是私有的、已删除或被地区封锁，/info 会返回一个错误，你可以立即呈现给用户——不会浪费一次下载尝试。这里 duration_seconds 字段也很有用，可用来拒绝直播或超过你应用允许时长的视频。

缩略图与时长

thumbnail 字段是 YouTube 为该视频提供的最高分辨率图片，因此你无需第二次请求即可渲染预览卡片。duration_str 已经格式化为 HH:MM:SS（不足一小时则为 MM:SS），而 duration_seconds 则给你原始整数，便于自行格式化或过滤。

费用

每次 GET /info 调用花费 6 个额度，新账户起始即有 100 个免费额度。由于 /info 会报告精确的文件大小，你可以让用户先选择格式，然后再花费一次 GET /create 下载所需的 10 个额度。

后续步骤

查看完整的 API 文档，了解 /info 的完整响应结构和每个字段，或将其与 GET /create 搭配，把读取到的元数据变成一个直接下载 URL。