Youtube到音频API的用例

您本周有一个功能要发布：将YouTube视频转换为您的应用可以下载、流式传输或处理的音频文件。在本文结束时，您将能够从Zyla API Hub调用Youtube到音频API，将YouTube视频解析为MP3下载URL或从YouTube URL触发下载流程，然后将生成的音频集成到您的管道中。

Youtube到音频API提供的功能

Youtube到音频API公开了两个简单的GET端点，将YouTube视频转换为音频。一个端点接受YouTube视频ID并返回一个准备下载的MP3链接以及有用的元数据（标题、时长、文件大小）。另一个接受完整的YouTube URL并返回一个下载URL，您可以获取以获得音频。

典型的消费者包括：

• 将长视频转换为音频亮点的播客剪辑工具。
• 需要在将音频发送到语音转文本引擎之前获取MP3的转录和语音分析服务。
• 从YouTube索引口语内容的知识库构建者。
• 将视频播放列表批量转换为音频以进行下游处理的内容自动化或AI代理。

在Zyla API Hub上开始

要使用这些端点，请打开Zyla API Hub上的API列表，订阅并获取您的API密钥。身份验证是在每个请求上的单个HTTP头：Authorization: Bearer YOUR_API_KEY。Zyla使用订阅+配额模型（而不是按调用付费）。您帐户上的第一个API提供7天的试用或50个请求；请查看API页面以获取当前访问选项和定价。从这里开始：

在Youtube到音频API上开始7天试用

您将使用的端点

基础：所有调用直接发送到下面显示的Zyla API Hub URL。请勿添加超出文档记录的额外查询参数。

1) 获取音频（按YouTube视频ID）

方法：GET

URL：https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio

描述：提供一个YouTube视频ID并接收一个包含直接MP3链接和元数据的对象。必需的参数：

• id（字符串）：YouTube视频ID。

官方curl示例：

curl -s -X GET "https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio?id=xFYQQPAOz7Y"
-H "Authorization: Bearer YOUR_API_KEY"

官方JSON响应：

{
"msg": "success",
"link": "https://theta.123tokyo.xyz/get.php/d/fa/xFYQQPAOz7Y.mp3?n=Eminem%20-%20Lose%20Yourself&uT=R&uN=QWxlam9aeWxhTGFicw%3D%3D&h=TcO7xrzRPZ9cGbw2wXP93w&s=1784312338&uT=R&uN=QWxlam9aeWxhTGFicw%3D%3D",
"status": "ok",
"duration": 327.49718169275,
"title": "Eminem - Lose Yourself",
"progress": 100,
"pc": 0,
"filesize": 4181397
}

如何使用这些字段：

• link：直接的、时间敏感的MP3 URL。执行第二个GET以下载音频字节。
• title：可读的标题。用于文件命名或用户界面。
• duration：视频/音频长度，浮点数（秒）。
• filesize：文件大小（字节），用于预分配存储或显示进度条。
• status/msg/progress/pc：您可以记录或显示的操作状态指示器，以便调试。

2) 下载音频（按完整YouTube URL）

方法：GET

URL：https://zylalabs.com/api/381/youtube-to-audio-api/22174/download-audio

描述：提供完整的YouTube URL并接收一个您可以获取以下载音频的URL。必需的参数：

• url（字符串）：完整的YouTube视频URL。

官方curl示例：

官方JSON响应：

如何使用此字段：

• downloadUrl：获取此URL以检索音频二进制文件。在大多数应用中，您将字节流式传输到磁盘或云存储。

Python示例：解析YouTube ID并下载MP3

此示例演示如何调用获取音频，读取元数据并下载MP3文件。它使用上面显示的确切端点和参数。

import os
import sys
import requests

API_KEY = os.getenv("ZYLALABS_API_KEY", "YOUR_API_KEY")
VIDEO_ID = "xFYQQPAOz7Y" # 在官方示例中提供
OUTFILE = "audio.mp3"

session = requests.Session()
headers = {"Authorization": f"Bearer {API_KEY}"}

# 1) 将YouTube ID解析为MP3链接 + 元数据
meta_url = "https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio"
resp = session.get(meta_url, headers=headers, params={"id": VIDEO_ID}, timeout=60)
resp.raise_for_status()
data = resp.json()

if data.get("status") != "ok" or not data.get("link"):
print("无法解析音频。", file=sys.stderr)
print(data, file=sys.stderr)
sys.exit(1)

mp3_url = data["link"]
title = data.get("title")
duration = data.get("duration")
filesize = data.get("filesize")

print(f"解析：title={title}, duration_s={duration}, bytes={filesize}")
print("正在下载音频...")

# 2) 下载MP3流
with session.get(mp3_url, stream=True, timeout=120) as r:
r.raise_for_status()
with open(OUTFILE, "wb") as f:
for chunk in r.iter_content(chunk_size=1024 * 128):
if chunk:
f.write(chunk)

# 3) 可选：如果提供了标题，则使用标题重命名
if title:
safe = "".join(c for c in title if c.isalnum() or c in (" ", "-", "_")).rstrip()
new_name = f"{safe}.mp3"
try:
os.replace(OUTFILE, new_name)
print(f"已保存：{new_name}")
except Exception:
print(f"已保存：{OUTFILE}（重命名失败，请检查文件系统权限）")

print("完成。")

注意：

• 第一次请求检索元数据和直接的MP3链接。第二次请求下载二进制流。
• 对于大文件，使用流式下载以避免将整个文件加载到内存中。
• 使用文件大小字段（字节）来预设进度条。时长以秒为单位，这可以帮助估算转录或处理成本。

您本周可以发布的实际用例

• 自动转录管道：将YouTube视频转换为MP3并将音频输入到您的语音转文本服务中。存储转录以供搜索、摘要或质量保证。
• 新闻通讯的音频剪辑器：提取音频亮点用于您的每周新闻通讯，而无需编写自己的下载器或维护抓取器。
• 知识索引：将讲座或演讲转换为音频，然后拆分为块以便在您的RAG堆栈中嵌入和检索。
• AI内容丰富：将MP3用作对话或关键词提取的输入，以改善内容推荐。
• 使用队列进行批处理：将YouTube ID或URL推送到队列中；工作者调用API，持久化音频，并发出包含结果文件路径和元数据的事件。

节省时间的实施细节

• 身份验证：在每个GET请求中始终发送Authorization: Bearer YOUR_API_KEY到Zyla端点。
• 两步流程：API返回链接或downloadUrl。执行第二个GET到该URL以检索音频字节。处理标准HTTP行为（重定向、超时）。
• 文件命名：使用标题字段作为人性化的文件名。考虑添加YouTube ID以实现幂等性（例如，"{title}-{id}.mp3"）。
• 存储：对于云上传，直接流式传输到您的对象存储SDK，以避免临时本地文件。使用文件大小在可用时设置Content-Length。
• 重试：下载URL的网络跳转在您的VPC之外。对瞬态5xx/连接错误实现重试和回退。
• 清理：在将用户提供的URL传递给下载音频端点之前进行清理，但不要更改预期的查询参数名称（url）。
• 速率和配额：Zyla使用订阅+配额模型。跟踪您的使用情况并在工作负载激增时实现电路断路器。有关当前选项，请查看API的市场页面。

在两个端点之间选择

• 如果您已经有YouTube视频ID，请使用获取音频。您将获得直接的MP3链接和有用的元数据（时长、文件大小、标题）一次调用。
• 如果您的工作流程从粘贴或发现的YouTube URL开始，请使用下载音频。它返回一个downloadUrl，您可以获取以获得音频。

您甚至可以将它们结合起来：在可能的情况下将输入标准化为ID（以便去重和缓存），但在用户粘贴完整链接时回退到URL流程。

通过MCP从AI代理调用API

Zyla上的每个API也可以通过MCP兼容的端点调用，地址为https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY。这适用于Claude Code、Cursor、Windsurf和其他MCP客户端中的代理。您配置MCP工具以发出与上面显示的相同的HTTP GET请求，带有Authorization头和确切的Zyla URL。有关使用MCP兼容客户端与Zyla工具的详细信息，从这里开始：

MCP

典型的代理模式：

• “给定视频ID，获取音频并发送到我的转录工具。”
• “当任务中出现YouTube链接时，解析为MP3，存储到S3，并返回存储URL。”

最小的端到端工作流程（基于ID）

1. 解析音频：
   • GET https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio?id=YOUR_VIDEO_ID，带有Authorization头。
2. 持久化元数据：
   • 存储标题、时长（秒）、文件大小（字节）以及原始YouTube ID以供后续参考。
3. 下载：
   • GET链接字段以流式传输MP3。保存到磁盘或对象存储。
4. 下游处理：
   • 根据需要启动转录、分块或嵌入作业。

操作提示

• 超时：设置保守的超时（例如，元数据60秒，大文件120秒以上）和指数回退的重试。
• 可观察性：记录请求ID和YouTube ID/URL以追踪问题。还记录文件大小和时长以进行容量规划。
• 缓存：按YouTube ID缓存成功的解析。如果链接过期，请再次调用API以刷新它。
• 安全性：不要在客户端暴露您的API密钥。通过您的后端服务路由调用。

常见问题

问：API需要什么身份验证？
答：在每个请求中发送Authorization: Bearer YOUR_API_KEY到Zyla端点。

问：每个端点需要哪些参数？
答：获取音频需要id（YouTube视频ID）。下载音频需要url（完整的YouTube URL）。请勿添加其他参数。

问：时长和文件大小代表什么？
答：duration是表示秒的浮点数。filesize是音频文件的大小（字节）。

问：我可以直接将结果流式传输到云存储吗？
答：可以。获取链接（或downloadUrl）并启用流式传输，将块直接写入您的存储SDK。

问：我如何尝试API？
答：在API的市场页面上订阅以获取API密钥。您帐户上的第一个API包括7天的试用或50个请求；请查看API页面以获取当前详细信息。

如果您准备好构建，请在Youtube到音频API的市场项目页面上订阅以获取您的密钥，复制上面的curl，并将其连接到您的下载器或转录管道。7天的试用从项目页面开始，端点在您准备好时即可使用。