YouTube to MP3 API

Convert a public YouTube video into an MP3 file. Send a regular YouTube link, then poll the run until the MP3 download URL is ready.

POST /v1/youtube/to-mp3

Canonical execution route: /v1/tasks/youtube-to-mp3/runs. For the live task contract, inspect GET /v1/tasks/youtube-to-mp3.

Downloading your MP3

No YouTube Studio login is required.
MP3 exports are kept for 24 hours. Signed download URLs are temporary.

Pricing and Limits

Item	Value
Credits	10 credits per started 10 minutes of video. Minimum cost is 10 credits.
Maximum duration	Up to 12 hours.
Maximum source size	1.5 GB.
Execution mode	Use async mode and poll `status_url`.

Parameters

Parameter	Type	Required	Description
video_url	string	Yes	A YouTube watch URL, youtu.be URL, shorts URL, or video ID.
bitrate	string	No	MP3 bitrate. Defaults to `192k`. Allowed: `128k`, `192k`, `256k`, `320k`.
include_metadata	boolean	No	Defaults to `true`. Preserves basic video metadata when available.
_run.async	boolean	Recommended	Set to `true` and poll `status_url` for completion.

Response

{
  "run_id": "00000000-0000-4000-8000-000000000001",
  "task_key": "youtube-to-mp3",
  "task_name": "YouTube to MP3",
  "run_status": "queued",
  "status_url": "/v1/runs/00000000-0000-4000-8000-000000000001",
  "metadata": {
    "video": {
      "id": "dQw4w9WgXcQ",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "title": "Video title",
      "channel_title": "Channel name",
      "thumbnail_url": "https://...",
      "duration_seconds": 245
    }
  },
  "result": null,
  "error": null
}

Result fields

download_url - Temporary signed MP3 URL.

download_url_expires_at - Expiry for the signed download URL.

expires_at - Export artifact retention expiry.

metadata.video - Video title, thumbnail, channel, and duration when available during polling.

result_summary - MP3 format, bitrate, file size, source size, duration, and title.

Code Examples

RUN=$(curl -s -X POST "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/youtube/to-mp3" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "_run": { "async": true }
  }')

STATUS_URL=$(echo "$RUN" | jq -r '.status_url')

curl -s "https://api-ingress-worker-staging.browsable-staging.workers.dev$STATUS_URL" \
  -H "Authorization: Bearer YOUR_API_KEY"

Try it Out

The playground sends the required fields. For production use, prefer the async examples above and poll the returned status_url.

API Playground

Error Codes

400 Invalid YouTube URL

The URL is not a supported YouTube watch, youtu.be, shorts URL, or video ID.

401 Unauthorized

Missing or invalid API key.

403 Forbidden

Your account cannot execute the task, usually because of access or credits.

Conversion failed

The source was too large, too long, unavailable, or could not be converted.