如何使用 YouTube 下载和信息 API

您需要以编程方式获取特定 YouTube 视频或音频格式的可下载链接，并在本周内发送。到本文结束时，您将进行一次身份验证请求，以使用 Zyla API Hub 上的 YouTube 下载和信息 API 检索一个可立即使用的下载任务（带有进度链接和缩略图），将其连接到您的后端或自动化，并通过 MCP 从 AI 代理调用它。

此 API 为您提供的内容

YouTube 下载和信息 API 暴露了一个单一的、专注的端点，用于初始化给定 YouTube URL 的可下载资产，格式由您选择。它支持常规 YouTube 视频（不支持直播），并返回：

一个成功标志，指示请求是否被接受。
请求下载的一个不透明 id。
您可以立即在 UI 中显示的图像 URL（视频的缩略图）。
一个 progress_url，以便在需要时在您的应用外部监控作业的进度。

常见用途包括：

为合规审查或内容 QA 构建内部媒体下载器。
在您的产品中添加“保存到库”或“离线剪辑”功能。
提取音轨以进行转录或分析管道。

所有操作都通过您的 Zyla 账户和一个 API 密钥进行。Zyla API Hub 提供一个账户、一个 API 密钥和一个订阅模型，适用于市场上的所有 API。您可以在 zylalabs.com 浏览超过 10,000 个公共 API，并在同一个密钥后面集成多个服务。

在 Zyla API Hub 上开始

要开始：

打开 Zyla 上 API 的列表：在 YouTube 下载和信息 API 上开始 7 天试用。
点击订阅或开始免费试用（如果可用），并获取您的 API 密钥。
在每个请求的 Authorization 头中使用该密钥。

计费为订阅 + 配额（不是按调用付费）。对于首次使用，此 API 在其项目页面上提供 7 天试用。请查看 API 页面以获取当前访问选项和定价。

端点概述和格式

该 API 当前提供一个下载端点。您提供一个 YouTube 视频 URL 和一个格式，它会返回一个作业标识符、缩略图和一个进度链接。

方法：GET
URL： https://zylalabs.com/api/11016/youtube-download-and-info-api/20761/download
参数：
- url（字符串，必需）：完整的 YouTube 观看 URL（下面提供示例）。
- format（字符串，必需）：以下允许的视频或音频格式之一。

可用格式

视频格式：

360p
480p
720p
1080p
1440p
2160p

音频格式：

mp3
m4a
flac
opus
wav

在生产中需要注意的事项：

音频下载链接在 2 小时后过期。将此纳入您的用户体验，以避免过期链接。
此端点仅支持下载常规视频（不支持直播）。

您可以复制并运行的 cURL 请求

以下是使用 YouTube URL 和 720p 视频格式的官方可复制请求。将 YOUR_API_KEY 替换为您从 Zyla 获取的密钥：

curl -s -X GET "https://zylalabs.com/api/11016/youtube-download-and-info-api/20761/download?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DaGSKrC7dGcY&format=720" \
-H "Authorization: Bearer YOUR_API_KEY"

示例 JSON 响应

这是官方示例响应。它包括一个成功标志、此请求的稳定 id、视频缩略图的图像 URL，以及您可以用来检查作业状态的进度 URL：

{
"success": true,
"id": "2ec15939807689549d3f3115f168be6b9c868105",
"image": "https://i.ytimg.com/vi/aGSKrC7dGcY/hqdefault.jpg",
"progress_url": "https://youtube-api-progress-copy-development.up.railway.app/api/progress?id=2ec15939807689549d3f3115f168be6b9c868105"
}

您应该期望的其他有效请求的相同结构（值在运行时会有所不同）：

{
"success": true,
"id": "2ec15939807689549d3f3115f168be6b9c868105",
"image": "https://i.ytimg.com/vi/aGSKrC7dGcY/hqdefault.jpg",
"progress_url": "https://youtube-api-progress-copy-development.up.railway.app/api/progress?id=2ec15939807689549d3f3115f168be6b9c868105"
}

使用此架构来连接您的解析逻辑。例如，在下载作业开始时立即在您的 UI 中显示图像，并持久化 id 以将用户的操作与作业链接：

{
"success": true,
"id": "2ec15939807689549d3f3115f168be6b9c868105",
"image": "https://i.ytimg.com/vi/aGSKrC7dGcY/hqdefault.jpg",
"progress_url": "https://youtube-api-progress-copy-development.up.railway.app/api/progress?id=2ec15939807689549d3f3115f168be6b9c868105"
}

解释响应字段

success: true 表示请求被接受并创建了作业。
id: 结果作业的唯一标识符。将其与您的用户操作一起存储以便追踪。
image: 视频缩略图的直接 URL。对 UI 占位符和队列视图很有帮助。
progress_url: 您可以用来外部检查处理进度的链接。使用它提供面向用户的进度更新或内部监控。音频下载具有时间敏感的链接（在 2 小时后过期），因此请相应协调用户流程。

Python 示例：请求和解析

以下 Python 代码片段演示了如何调用下载端点、验证响应并提取您将在应用中实际使用的字段。它与 cURL 示例中显示的请求相匹配：

import os
import urllib.parse
import requests

API_KEY = os.environ.get("ZYLA_API_KEY", "YOUR_API_KEY")

BASE_URL = "https://zylalabs.com/api/11016/youtube-download-and-info-api/20761/download"

def request_download(youtube_url: str, fmt: str):
params = {
"url": youtube_url,
"format": fmt
}
headers = {
"Authorization": f"Bearer {API_KEY}"
}
# 如果您的 URL 包含特殊字符，在构建手动 URL 时对其进行 URL 编码；
# requests 将正确处理 params 字典。
resp = requests.get(BASE_URL, params=params, headers=headers, timeout=30)
resp.raise_for_status()
data = resp.json()
# 最小形状检查以确保健壮性
if not isinstance(data, dict) or "success" not in data:
raise ValueError("意外的响应形状")
if not data.get("success"):
# API 可能会因无效输入而返回 success=false；请优雅处理。
# 您可以记录数据以进行诊断。
raise RuntimeError(f"请求不成功：{data}")
# 提取您的应用将使用的字段：
job_id = data.get("id")
thumbnail = data.get("image")
progress_link = data.get("progress_url")
return job_id, thumbnail, progress_link

if __name__ == "__main__":
video_url = "https://www.youtube.com/watch?v=aGSKrC7dGcY"
format_choice = "720" # 使用任何支持的格式：360p、480p、720p、1080p、1440p、2160p、mp3、m4a、flac、opus、wav
job_id, thumbnail, progress_link = request_download(video_url, format_choice)
print("作业 ID:", job_id)
print("缩略图:", thumbnail)
print("进度 URL:", progress_link)

供参考，这里是代码期望解析的官方 JSON：

{
"success": true,
"id": "2ec15939807689549d3f3115f168be6b9c868105",
"image": "https://i.ytimg.com/vi/aGSKrC7dGcY/hqdefault.jpg",
"progress_url": "https://youtube-api-progress-copy-development.up.railway.app/api/progress?id=2ec15939807689549d3f3115f168be6b9c868105"
}

格式选择和用户体验提示

在构建您的 UI 或 CLI 时，仅呈现您的工作流程可以在下游处理的格式。一些务实的指南：

对于最快的视频预览，360p 或 480p 就可以。对于归档或编辑，1080p 及以上。
对于仅音频转录，m4a 或 wav 是常见选择。请记住：音频下载链接在 2 小时后过期——在收到作业信息后立即进行最终获取。
如果用户选择非常高的分辨率（1440p/2160p），请告知他们处理和文件大小将更大。
立即从图像字段显示图像，以确认正确的视频，然后再完成下载。

操作准备：可靠性、幂等性和配额

为了在本周内顺利交付：

将返回的 id 绑定到您自己的数据库行，表示用户操作（例如，“DownloadRequest” 表）。这将为您提供可追溯性。
如果您为同一视频/格式对排队多个请求，请考虑在发出新的 API 调用之前，在您的侧面通过 YouTube URL + 格式进行去重。
通过记录响应体并仅在适当时重试来处理非 200 HTTP 响应。不要盲目循环重试。
请记住 Zyla 的订阅 + 配额模型。监控您在 Zyla 仪表板上的剩余配额，并在大规模操作时考虑反压。
由于音频下载链接在 2 小时后过期，因此：
- 在准备存储后立即在您的后端启动最终文件获取，或
- 提示用户在时间窗口内下载，并提供一键刷新流程，在需要时重新调用 API。

Zyla 统一了 API 的身份验证和访问，因此您可以稍后添加相关工具，而无需新的密钥。在 zylalabs.com 上探索更多媒体服务。

现实世界集成模式

内部审查队列：创建一个小服务，接受 YouTube URL 和目标格式。提交时，调用下载端点，存储 id，并立即显示图像。后台工作者可以定期检查进度 URL，并在资产准备好时通知审阅者。
播客音频提取：提供 mp3 或 m4a 作为选择。在用户粘贴链接后立即触发下载端点；一旦文件在您的下游流程中准备好，立即将其发送到您的转录引擎。由于 2 小时的音频链接窗口，请紧密连接这些步骤。
LMS 中的离线模块：对于嵌入 YouTube 课程的课程，预请求 480p 或 720p 版本。在下载在后台完成时，存储作业 id 并在课程列表中显示图像缩略图。

通过 MCP 从 AI 代理调用 API

如果您使用兼容 MCP 的客户端（例如，Claude Code、Cursor、Windsurf），您可以让代理通过 MCP 网关调用 Zyla API。在 MCP 端点中提供您的 Zyla API 密钥，并指示代理执行对 Hub URL 的身份验证 GET 请求：

MCP 端点： MCP
将您的 API 密钥传递为： https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
让代理调用：
- GET https://zylalabs.com/api/11016/youtube-download-and-info-api/20761/download
- 查询参数：url，format
- 头：Authorization: Bearer YOUR_API_KEY

用自然语言，您可以告诉您的代理：“使用此 YouTube URL 和格式 720 调用 YouTube 下载和信息 API 的下载端点，包含 Authorization: Bearer，并返回 id、image 和 progress_url。”与官方示例相同的结构适用。使用返回的 id 来标记代理工作流中的后续步骤。

故障排除和验证检查清单

身份验证错误：确保 Authorization 头完全是“Bearer YOUR_API_KEY”，并且是您从 Zyla 仪表板获取的有效密钥。
输入错误：验证 url 是否为完整的 YouTube 观看 URL。确保格式是列出的值之一，并在连接到 URL 时正确编码。
时间敏感的音频链接：如果用户在 2 小时后尝试获取音频对象，请重新运行请求并及时启动下载。
不支持的内容类型：此端点仅处理常规视频。如果源是直播，请告知用户并禁止该操作。
网络可靠性：添加简单的退避并记录非 2xx 响应的主体，以加速调试。

安全考虑

将您的 Zyla API 密钥存储在您的秘密管理器或环境变量中；切勿在客户端代码中硬编码。
在将用户提交的 YouTube URL 发送到 API 之前，对其进行清理和验证。
切勿将您的 API 密钥代理到不受信任的前端。优先考虑在受信任的环境中进行服务器端调用或代理端工具。

参考：官方请求和响应

为了方便，这里再次提供官方块以供快速复制/粘贴。

请求

curl -s -X GET "https://zylalabs.com/api/11016/youtube-download-and-info-api/20761/download?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DaGSKrC7dGcY&format=720" \
-H "Authorization: Bearer YOUR_API_KEY"

响应

{
"success": true,
"id": "2ec15939807689549d3f3115f168be6b9c868105",
"image": "https://i.ytimg.com/vi/aGSKrC7dGcY/hqdefault.jpg",
"progress_url": "https://youtube-api-progress-copy-development.up.railway.app/api/progress?id=2ec15939807689549d3f3115f168be6b9c868105"
}

常见问题

我可以请求哪些格式？
视频：360p、480p、720p、1080p、1440p、2160p。音频：mp3、m4a、flac、opus、wav。

我如何进行身份验证？
在每个请求中包含头 Authorization: Bearer YOUR_API_KEY。在您订阅后，在 API 的 Zyla 列表中获取您的密钥。

音频链接会过期吗？
是的。音频下载链接在 2 小时后过期。请及时启动最终下载，或在需要时重新调用 API。

支持直播吗？
不支持。该端点仅支持下载常规视频。

我如何开始试用？
使用 Zyla 上的项目页面开始您的 7 天试用：在 YouTube 下载和信息 API 上开始 7 天试用。

交付它

您可以在不到一小时的时间内集成 YouTube 下载和信息 API：调用下载端点，提供 url 和 format，读取 id/image/progress_url，并连接一个短暂的后台任务以完成您的工作流程。在 Zyla 上创建您的账户，并从列表中开始 7 天试用，以获取您的 API 密钥并在本周上线。