YouTube to MP3 converter API
Convert a public YouTube video to MP3, M4A, WAV, FLAC, or four more formats with one POST. The response returns a permanent audio download URL and normalized track metadata.
- One POST, One Audio File
- Permanent Download URLs
- Eight Formats, Seven Bitrates
- Bounded, Predictable Cost
- Idempotent By Design
- Honest Error Contract
Request examples
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"}'Response examples
Documented responses from the OpenAPI specification.
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"
}Features
The youtube.audio_download operation converts one public YouTube video into a saved audio file. Your server holds the API key; the endpoint returns a permanent download URL plus normalized metadata in a single call.
One POST, One Audio File
Send POST /v1/youtube/audio/download with a public YouTube URL and optional format and bitrate. A successful 200 returns video_id, url, title, channel, duration_seconds, audio_url, thumbnail_url, format, bitrate, and file_size_bytes — everything a downloader pipeline needs in one response.
Permanent Download URLs
The audio_url points to a fully saved file, not an expiring CDN redirect. It downloads from any server, any IP, at any time, so you can hand it to a queue worker, a media server, or straight to your end user without re-running the conversion.
Eight Formats, Seven Bitrates
The format parameter accepts mp3 (default), m4a, wav, aac, flac, opus, vorbis, and alac. The bitrate parameter accepts source, auto (default), 320k, 256k, 192k, 128k, and 64k. Lossless formats ignore bitrate; a requested bitrate never exceeds the source stream.
Bounded, Predictable Cost
Each call converts exactly one video at a fixed price — playlist URLs are rejected and an upstream cost guard declines videos beyond roughly 25 minutes. Your integration never faces an unbounded per-call charge, and failed conversions are not billed.
Idempotent By Design
Send an Idempotency-Key header with every request. Retried calls with the same key return the original result without double-charging, which makes safe retries over flaky networks straightforward: 409 signals a key conflict, not a second conversion.
Honest Error Contract
400 means the URL, format, or bitrate is invalid; 401 means the key is missing or wrong; 502/503/504 mean the upstream conversion failed and deserve a backoff retry. Private and age-restricted videos surface as upstream errors because the platform itself refuses them.
How to use
Integrate the YouTube to MP3 converter API in six steps with curl or any HTTP client.
Create An API Key
Sign up for a free AgentBody account and create an API key in the console. Keep the key on your server — it must never ship in a browser or mobile client bundle.
Pick A Public Video
Choose a public YouTube video and take its URL in any common shape: watch page, youtu.be short link, Shorts, or embed URL. The endpoint validates the URL before any paid work starts.
POST The Conversion Request
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"}'. Both format and bitrate are optional and default to mp3 and auto.
Poll Or Wait For 200
The call is synchronous and typically returns within a couple of minutes because the file is fully downloaded and saved. Set your HTTP client timeout to at least five minutes and treat 504 as a retryable timeout, not a failed conversion.
Read The Response
On 200, take audio_url for the file itself and the metadata fields — title, channel, duration_seconds, file_size_bytes, thumbnail_url — for display or storage. The format and bitrate fields echo what was actually produced.
Deliver Or Store The File
Stream the file from audio_url to your own storage if you want full control, or pass the link to your user directly. Because the URL is permanent, both patterns work without re-calling the API.
Frequently asked questions
What does a conversion cost?
Each successful conversion is billed at a fixed price shown on your account's pricing page — the site never hardcodes it because the gateway governs pricing. Failed conversions are not charged, and the fixed price holds regardless of format or bitrate because long videos are capped upstream.
Which request fields are required?
Only url is required: a public YouTube video URL (watch, youtu.be, Shorts, or embed). format defaults to mp3 and accepts m4a, wav, aac, flac, opus, vorbis, and alac; bitrate defaults to auto and accepts source, 320k, 256k, 192k, 128k, and 64k.
Why does the call take up to a few minutes?
Unlike converters that return an expiring CDN link, this API fully downloads and saves the audio file before responding, which is what makes the returned URL permanent. A typical song finishes in one to three minutes; allow a five-minute client timeout and retry on 504.
Can I convert playlists or long podcasts?
No. The endpoint converts exactly one video per call and rejects playlist URLs. Videos longer than roughly 25 minutes are declined by an upstream cost guard that keeps the fixed price sustainable; batch jobs should enqueue one call per video with distinct idempotency keys.
How do retries and idempotency work?
Include a unique Idempotency-Key per conversion. A retry with the same key returns the original result without a second charge; a 409 means the key was already used with different parameters. Network failures and 5xx responses are safe to retry under the same key.
What content can the API not convert?
Private, unlisted, and age-restricted videos cannot be converted because the platform itself refuses access — they surface as upstream errors. Convert only public content you own, have permission to save, or have another lawful basis to download, in line with copyright law and YouTube's terms.