AgentBodyAgentBody
登录

YouTube 转 MP3 转换器 API

一次 POST 把公开 YouTube 视频转成 MP3、M4A、WAV、FLAC 等八种格式。响应返回永久音频下载地址和规范化曲目元数据。

  • 一次 POST，一个音频文件
  • 永久下载地址
  • 八种格式，七档码率
  • 成本有界可预期
  • 幂等设计
  • 诚实的错误契约
工具APIAgent

请求示例

查看 API 文档 完整 API 文档 
curl -X POST "https://api.agentbody.io/v1/youtube/audio/download" \
  -H "Authorization: Bearer <YOUR_AGENTBODY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"bitrate":"source","format":"mp3","url":"YOUR_URL"}'

响应示例

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

Retained audio file URL and normalized public track metadata.

{
  "audio_url": "https://example.com/audio-dQw4w9WgXcQ.mp3",
  "bitrate": "192k",
  "channel": "Example Channel",
  "duration_seconds": 212,
  "file_size_bytes": 3407872,
  "format": "mp3",
  "thumbnail_url": "https://example.com/thumbnail-dQw4w9WgXcQ",
  "title": "Example Track",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "video_id": "dQw4w9WgXcQ"
}

功能特点

youtube.audio_download 操作把一个公开 YouTube 视频转成保存好的音频文件。密钥放在你的服务端；接口在一次调用里返回永久下载地址和规范化元数据。

一次 POST，一个音频文件

向 POST /v1/youtube/audio/download 发送公开 YouTube URL，可选 format 和 bitrate。200 成功响应包含 video_id、url、title、channel、duration_seconds、audio_url、thumbnail_url、format、bitrate、file_size_bytes——下载管线需要的字段一次给全。

永久下载地址

audio_url 指向完整保存的文件，不是会过期的 CDN 跳转。任何服务器、任何 IP、任何时间都能下载，可以直接交给队列 worker、媒体服务器或终端用户，无需重复转换。

八种格式，七档码率

format 参数接受 mp3（默认）、m4a、wav、aac、flac、opus、vorbis、alac。bitrate 参数接受 source、auto（默认）、320k、256k、192k、128k、64k。无损格式忽略码率；指定码率不会超过源音频流。

成本有界可预期

每次调用只转换一个视频，固定价格——播放列表 URL 被拒绝，上游成本保护会拒绝约 25 分钟以上的视频。你的集成永远面对可预期的单次费用，转换失败不计费。

幂等设计

每个请求带上 Idempotency-Key 头。相同密钥的重试返回原始结果，不重复扣费——在不稳定的网络上安全重试很简单：409 表示密钥冲突，而不是第二次转换。

诚实的错误契约

400 表示 URL、格式或码率无效；401 表示密钥缺失或错误；502/503/504 表示上游转换失败，应退避重试。私密和年龄限制视频会表现为上游错误，因为平台本身拒绝访问。

使用步骤

六步接入 YouTube 转 MP3 转换器 API，curl 或任何 HTTP 客户端均可。

01

创建 API 密钥

注册免费 AgentBody 账号，在控制台创建 API 密钥。密钥只能放在你的服务端——绝不能打进浏览器或移动客户端的包。

02

选一个公开视频

选一个公开 YouTube 视频，取任意常见形态的 URL：watch 页、youtu.be 短链、Shorts 或 embed 链接。接口会在任何计费工作开始前先校验 URL。

03

POST 转换请求

curl -X POST https://api.agentbody.io/v1/youtube/audio/download -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: <uuid>" -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","format":"mp3"}'。format 和 bitrate 均可选，默认 mp3 和 auto。

04

等待 200 返回

调用是同步的，通常几分钟内返回，因为文件是完整下载保存的。HTTP 客户端超时建议至少五分钟；504 视为可重试的超时，而不是转换失败。

05

读取响应

200 时取 audio_url 拿文件本身，元数据字段——title、channel、duration_seconds、file_size_bytes、thumbnail_url——用于展示或存储。format 和 bitrate 字段回显实际产出。

06

转存或分发文件

想要完全掌控就把文件从 audio_url 流式转存到你自己的存储，或者直接把链接交给用户。因为 URL 永久有效，两种模式都不需要再调一次 API。

常见问题

一次转换多少钱？

每次成功转换按账号定价页显示的固定价格计费——站点不写死数字，因为价格由网关管理。失败的转换不计费；因为长视频在上游被限制，固定价格与格式、码率无关。

哪些请求字段是必填的？

只有 url 必填：公开 YouTube 视频 URL（watch、youtu.be、Shorts 或 embed）。format 默认 mp3，可选 m4a、wav、aac、flac、opus、vorbis、alac；bitrate 默认 auto，可选 source、320k、256k、192k、128k、64k。

为什么调用要几分钟？

与返回临时 CDN 链接的转换器不同，这个 API 在响应前会把音频文件完整下载并保存，这正是返回 URL 永久有效的原因。典型歌曲 1-3 分钟完成；客户端超时留五分钟，504 可重试。

能转播放列表或长播客吗？

不能。接口每次调用只转换一个视频，拒绝播放列表 URL。约 25 分钟以上的视频被上游成本保护拒绝，以保证固定价格可持续；批量任务应每个视频一次调用，各用独立幂等键排队。

重试和幂等怎么处理？

每次转换带一个唯一 Idempotency-Key。相同密钥的重试返回原始结果，不二次扣费；409 表示该密钥已用于不同参数。网络失败和 5xx 响应都可以用同一密钥安全重试。

API 不能转换什么内容？

私密、不公开和年龄限制视频无法转换，因为平台本身拒绝访问——表现为上游错误。只转换你拥有、已获授权或有其他合法依据的公开内容，遵守版权法和 YouTube 服务条款。