YouTube 视频下载 API

一次带鉴权的 POST 把公开 YouTube 链接转成已保存的 MP4——144p 到 720p 画质选择、视频直链和规范化元数据，干净 JSON 返回。

单一 REST 端点
画质选择器
规范化元数据
幂等的计费写入
可预期的错误码
五语言示例

请求示例

curl -X POST "https://api.agentbody.io/v1/youtube/video/download" \
  -H "Authorization: Bearer <YOUR_AGENTBODY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"quality":"144p","url":"YOUR_URL"}'

响应示例

来自 OpenAPI 规范的已文档化响应。

Downloaded YouTube media link and normalized public video metadata.

{
  "duration_seconds": 180,
  "format": "mp4",
  "quality": "720p",
  "size_mb": 15.2,
  "title": "Example Video",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "video_content_type": "video/mp4",
  "video_id": "dQw4w9WgXcQ",
  "video_url": "https://api.apify.com/v2/key-value-stores/example/records/dQw4w9WgXcQ.mp4"
}

功能特点

用 YouTube 视频下载 API 搭建存档管线、离线内容系统和媒体工作流——URL 进，MP4 链接出。

单一 REST 端点

带 bearer API 密钥和公开视频 URL 调用 POST /v1/youtube/video/download。API 保存 MP4 并返回视频直链——无需无头浏览器、无需维护 yt-dlp、无需轮换代理。

画质选择器

quality 字段接受 144p、240p、360p、480p、720p。每次请求钉死想要的输出，响应确认实际交付的画质、格式和大小。

规范化元数据

每个响应把 video_url 与 video_id、title、duration_seconds、format、quality、size_mb、video_content_type 配对——管线可直接存储的稳定字段，无需逐请求解析。

幂等的计费写入

视频保存是按量计费操作。重试时带 Idempotency-Key 头，中断的响应不会重复计费同一视频——同键的相同重复请求返回原始结果。

可预期的错误码

用文档化状态码处理失败：400 请求无效、401 密钥缺失或错误、409 幂等冲突、502/503/504 暂时性上游问题——每类对应明确的修复或重试动作。

五语言示例

本页从端点的 OpenAPI 定义直接生成 curl、JavaScript、Python、Java、Go 请求示例——用你技术栈已有的 HTTP 客户端即可。

使用步骤

按以下步骤调用 YouTube 视频下载 API：创建密钥，构造 POST 请求，处理返回的 MP4 链接。

创建 API 密钥

创建 AgentBody 账号并在控制台生成 API 密钥。密钥放在服务端环境或受认可的密钥库，以 bearer 令牌发送——绝不进浏览器代码或客户端包。

构造请求

向 /v1/youtube/video/download 发送 POST，带必填的 url 和可选的 quality（144p/240p/360p/480p/720p）。生成示例展示 curl、JavaScript、Python、Java、Go 的确切请求。

加幂等键

给每个可能重试的下载附 Idempotency-Key 头——超时、断连、worker 重启。同键的重复相同请求返回原始响应，不重复计费。

密钥留在服务端

从后端、serverless 函数或定时任务调用端点。若终端用户触发下载，经你自己的端点代理，让密钥和计额掌控在你手里。

解析 JSON 响应

读取返回的 video_url、video_id、title、duration_seconds、format、quality、size_mb。把链接和元数据一起存储，或把 URL 直接交给存储层——字段跨请求稳定。

正确处理错误

400 修请求体，401 配好密钥，409 按文档化幂等键行为处理。502/503/504 同键带退避重试。

常见问题

YouTube 视频下载 API 是什么？

一个带鉴权的 POST 端点 /v1/youtube/video/download，把一条公开 YouTube 视频保存为 MP4，返回视频直链和规范化元数据——video_id、标题、时长、格式、画质、大小——以结构化 JSON 交付。

YouTube 下载 API 的价格怎么算？

每次视频保存是消耗账号额度的按量计费操作。价格由网关管理，而非本页写死的数字——在控制台查看当前单价，并用幂等键确保重试不双重计费。

YouTube 下载 API 支持哪些画质？

quality 字段接受 144p、240p、360p、480p、720p。本 API 最高 720p——没有 1080p 或 4K 档位。响应回报实际交付的画质。

能替代 yt-dlp 或自建爬虫吗？

对 720p 以内的公开视频可以。不用再维护 yt-dlp 升级、格式协商和代理处理，调用一个文档化 REST 端点，拿到带文件链接的稳定 JSON。

API 能下载私密或会员专属视频吗？

不能。端点只读取公开视频——私密、会员专属和已删除视频不会解析，也不会索要 YouTube 凭据来绕过限制。

怎么处理 API 错误？

400 修请求体，401 修 bearer 密钥，409 按文档化幂等键行为处理。把 502、503、504 当作暂时性上游故障，同键带退避重试。