您的任务:获取一个 YouTube 链接或视频 ID,并以编程方式获取一个可下载的 MP3 URL,您可以在应用中保存或流式传输。到本文结束时,您将调用一个返回直接音频链接和元数据的真实端点,然后编写几行代码来下载文件。
您可以用此构建什么
Zyla API Hub 上的 YouTube 到音频 API 让您将 YouTube 视频转换为音频下载 URL。它返回音频文件的链接以及有用的元数据,如标题、时长和文件大小。开发人员使用它来:
- 从公共 YouTube 视频生成 MP3,以便在播客或学习应用中离线播放。
- 将音频提取作业排队作为更大媒体工作流的一部分。
- 通过返回一个可以被您的服务下载或代理的单一 URL 简化内容摄取。
此 API 专注于两个具体操作:给定视频 ID,返回音频链接和元数据;或者,给定完整的 YouTube URL,返回一个准备下载的 URL。没有 SDK 需要处理,只需简单的 HTTP GET 调用。
在 Zyla API Hub 上开始
Zyla API Hub 通过一个帐户、一个 API 密钥和一致的订阅模型提供数千个生产就绪的 API。您可以浏览、订阅并调用 API,而无需设置多个供应商帐户。在 zylalabs.com 上探索更多内容。
要使用此 API:
- 打开 Zyla API Hub 上的 YouTube 到音频 API 的 7 天试用开始 页面。
- 点击订阅(或在可用时点击开始免费试用)并获取您的 API 密钥。
- 发送请求时使用头部 Authorization: Bearer YOUR_API_KEY。
计费是基于配额的订阅,而不是按调用付费。请查看 API 页面以获取当前访问选项和定价。您还可以在 zylalabs.com 上发现更多 API 和类别。
API 概述
YouTube 到音频 API 通过 Zyla 的 API 网关公开两个 GET 端点:
- 获取音频(按 YouTube 视频 ID):返回直接音频链接和元数据
- 下载音频(按完整 YouTube URL):返回下载 URL
所有请求都使用 HTTPS,并要求 Authorization 头部带有 Bearer API 密钥。下面的示例可以直接复制粘贴。
端点:获取音频(按视频 ID)
当您拥有 YouTube 视频 ID 并需要音频链接以及标题、时长和文件大小等元数据时,请使用此方法。
- 方法:GET
- URL:https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio
- 所需查询参数:id
示例请求:
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:生成的音频文件的直接 URL。使用此链接进行流式传输或保存 MP3。
- title:源视频的标题,适用于文件名和 UI 标签。
- duration:表示时长的浮点值(以秒为单位)。
- filesize:可下载音频的字节大小,有助于进度条和存储规划。
- status/msg/progress:状态指示器;在此示例中,progress 是一个类似百分比的数字。
Python 示例:获取音频链接并下载 MP3
此示例调用获取音频端点,提取链接字段,并将文件下载到磁盘。将 YOUR_API_KEY 替换为您在市场页面上的密钥。
import os
import sys
import requests
API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
VIDEO_ID = "xFYQQPAOz7Y" # 在示例请求中提供
try:
# 步骤 1:获取音频元数据和链接
meta_resp = requests.get(
"https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"id": VIDEO_ID},
timeout=30,
)
meta_resp.raise_for_status()
data = meta_resp.json()
if data.get("status") != "ok" or "link" not in data:
print("音频未准备好或失败:", data)
sys.exit(1)
audio_url = data["link"]
title = data.get("title", f"{VIDEO_ID}.mp3")
duration = data.get("duration")
size_bytes = data.get("filesize")
# 选择文件名。如果标题存在,则生成安全文件名。
filename = f"{title}.mp3" if not title.endswith(".mp3") else title
safe_filename = filename.replace("/", "_")
print(f"正在下载:{safe_filename}")
print(f"时长(秒):{duration}")
print(f"文件大小(字节):{size_bytes}")
print(f"URL:{audio_url}")
# 步骤 2:下载 MP3
with requests.get(audio_url, stream=True, timeout=60) as r:
r.raise_for_status()
with open(safe_filename, "wb") as f:
for chunk in r.iter_content(chunk_size=8192):
if chunk:
f.write(chunk)
print("已保存到:", safe_filename)
except requests.HTTPError as e:
print("HTTP 错误:", e, file=sys.stderr)
sys.exit(1)
except requests.RequestException as e:
print("请求失败:", e, file=sys.stderr)
sys.exit(1)
提示:由于响应包含文件大小,您可以预分配进度条。如果文件大小不可用,则通过计算写入的字节来流式传输并推断进度。
端点:下载音频(按完整 YouTube URL)
当您拥有完整的 YouTube 视频 URL 并且只需要下载 URL 时,请使用此方法。此端点返回一个 downloadUrl 字段,您可以在第二步中获取。
- 方法:GET
- URL:https://zylalabs.com/api/381/youtube-to-audio-api/22174/download-audio
- 所需查询参数:url
示例请求:
示例 JSON 响应:
在典型流程中,调用此端点以获取 downloadUrl,然后对该 URL 执行标准 HTTP GET 以检索二进制音频内容。如果您需要标题、时长或文件大小,请优先使用获取音频端点,该端点将这些字段与链接一起显示。
您应该使用哪个端点?
- 当您已经拥有视频 ID 并希望在一个响应中获取元数据(标题、时长、文件大小)以及链接时,请使用获取音频。
- 当您拥有完整的 YouTube URL 并且只需要一个可下载的 URL 时,请使用下载音频,然后在第二个请求中获取文件。
节省时间的实现细节
- 身份验证:始终发送 Authorization: Bearer YOUR_API_KEY。不要将密钥放在查询字符串中。
- 超时:调用是标准的 HTTPS GET。对元数据请求和文件下载请求设置实际的超时。文件下载可能需要更长时间;使用分块读取进行流式传输。
- 文件名:获取音频响应包括标题,这对于文件名很方便。根据您的操作系统进行清理。
- 时长和大小:时长是以秒为单位的浮点数;文件大小是字节。使用文件大小进行存储预算和进度指示。
- 缓存:如果您重复请求相同的视频 ID 或 URL,请在您的系统中缓存结果链接和元数据,并设置适合您工作流的过期策略。
- 重试:返回文件链接的网络请求经过与 Zyla 网关不同的主机。如果下载失败,请重试并进行退避。
JavaScript(Node.js)中的端到端示例
此脚本使用 fetch 调用获取音频端点,然后使用返回的链接下载文件。使用 Node 18+ 或添加 fetch polyfill。
import fs from "node:fs";
import { pipeline } from "node:stream";
import { promisify } from "node:util";
const streamPipeline = promisify(pipeline);
const API_KEY = process.env.ZYLA_API_KEY || "YOUR_API_KEY";
const VIDEO_ID = "xFYQQPAOz7Y";
async function main() {
// 步骤 1:获取元数据 + 链接
const metaUrl = new URL("https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio");
metaUrl.searchParams.set("id", VIDEO_ID);
const metaResp = await fetch(metaUrl, {
method: "GET",
headers: { Authorization: `Bearer ${API_KEY}` },
});
if (!metaResp.ok) {
console.error("元数据请求失败:", metaResp.status, await metaResp.text());
process.exit(1);
}
const data = await metaResp.json();
if (data.status !== "ok" || !data.link) {
console.error("音频未准备好或缺少链接:", data);
process.exit(1);
}
const audioUrl = data.link;
const title = data.title || `${VIDEO_ID}.mp3`;
const filename = title.endsWith(".mp3") ? title : `${title}.mp3`;
console.log("正在下载:", filename);
console.log("时长(秒):", data.duration);
console.log("文件大小(字节):", data.filesize);
console.log("URL:", audioUrl);
// 步骤 2:下载文件
const fileResp = await fetch(audioUrl, { method: "GET" });
if (!fileResp.ok || !fileResp.body) {
console.error("下载失败:", fileResp.status, await fileResp.text());
process.exit(1);
}
await streamPipeline(fileResp.body, fs.createWriteStream(filename));
console.log("已保存到:", filename);
}
main().catch((err) => {
console.error(err);
process.exit(1);
});
现实世界模式
- 批处理处理:给定播放列表,将每个视频解析为其 ID,然后对每个 ID 调用获取音频。存储标题、文件大小和链接以供您的摄取管道使用。
- 为您的服务创建微型库:将这两个端点包装在一个小助手中,具有重试、超时和文件名清理功能。
- 后台作业:使用您的作业运行器排队 ID 到音频的转换。如果 data.status 或 progress 指示您的场景中存在异步工作,请轮询直到进度达到 100 再下载。
- 存储交接:不要直接提供外部链接,而是下载并重新上传到您自己的对象存储,以便进行一致的托管和访问控制。
通过 MCP 从 AI 代理调用
如果您将此连接到 AI 开发环境,您可以通过 Model Context Protocol 通过单个 MCP 端点调用 Zyla API。任何兼容 MCP 的客户端(例如 Claude Code、Cursor、Windsurf)都可以通过以下方式调用市场 API:
代理的端点:https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
在该 MCP 端点上使用您的 Zyla API 密钥与 apikey 查询参数,然后让您的代理通过其 MCP 传输执行上述相同的 HTTPS 调用。有关一般 MCP 信息,请参见 MCP 页面。
故障排除检查表
- 401 或 403 错误:确保 Authorization 头部设置为 Bearer YOUR_API_KEY,并且您的订阅处于活动状态。
- 响应中没有链接:对于获取音频端点,请检查状态和进度字段,如果需要,请在短暂延迟后重试。
- 下载在流中失败:使用退避重试文件请求,并考虑验证部分文件大小。
- 意外的标题或文件名:清理特殊字符,如果标题缺失,则回退到视频 ID。
安全和操作说明
- 绝不要将您的 API 密钥嵌入客户端代码中。通过您的后端代理请求或使用服务器端调用。
- 记录请求 ID 和时间戳,以简化调试和支持。
- 考虑内容政策和用户权限,以便对下载的音频进行任何下游分发。
后续步骤
一旦您验证了第一次请求,请将这些调用包装在您应用的服务层中,添加最小重试,并将进度事件连接到您的 UI。使用标题、时长和文件大小字段来标记和监控音频处理。
要立即尝试,请打开市场页面并获取 API 密钥:YouTube 到音频 API 的 7 天试用开始。您将获得基于订阅的访问权限,带有配额。请查看 API 页面以获取当前访问选项和定价。
常见问题
需要什么身份验证头?
在每个请求中发送 Authorization: Bearer YOUR_API_KEY 到 Zyla 端点。
哪个端点返回像标题和时长这样的元数据?
使用 GET https://zylalabs.com/api/381/youtube-to-audio-api/8884/get-audio,带有 id 参数。
我如何下载实际的音频文件?
调用其中一个 API 端点以获取链接或 downloadUrl,然后对返回的 URL 执行标准 HTTP GET 以检索二进制内容。
我可以从完整的 YouTube URL 开始,而不是 ID 吗?
可以。使用 GET https://zylalabs.com/api/381/youtube-to-audio-api/22174/download-audio,带有 url 参数。
是否有免费计划?
访问是基于配额的订阅。项目页面在可用时提供 7 天试用。请查看 API 页面以获取当前访问选项和定价。