# 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

```json
{
  "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

```bash
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"
```

```python
import time
import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

start = requests.post(
    "https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/youtube/to-mp3",
    headers=headers,
    json={
        "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "_run": {"async": True},
    },
)
start.raise_for_status()
run = start.json()

while run["run_status"] not in {"succeeded", "failed", "canceled"}:
    time.sleep(3)
    run = requests.get(f"https://api-ingress-worker-staging.browsable-staging.workers.dev{run['status_url']}", headers=headers).json()

if run["run_status"] == "succeeded":
    print(run["result"]["download_url"])
else:
    print(run["error"])
```

```javascript
const headers = {
  Authorization: "Bearer YOUR_API_KEY",
  "Content-Type": "application/json",
};

let run = await fetch("https://api-ingress-worker-staging.browsable-staging.workers.dev/v1/youtube/to-mp3", {
  method: "POST",
  headers,
  body: JSON.stringify({
    video_url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    _run: { async: true },
  }),
}).then((response) => response.json());

while (!["succeeded", "failed", "canceled"].includes(run.run_status)) {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  run = await fetch("https://api-ingress-worker-staging.browsable-staging.workers.dev" + run.status_url, { headers }).then((response) => response.json());
}

if (run.run_status === "succeeded") {
  console.log(run.result.download_url);
} else {
  console.error(run.error);
}
```

## 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

API Key

Stored locally only

video_url * 

YouTube watch, youtu.be, shorts URL, or video ID

## 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.

---
Source: https://browsable-api-ux-staging.pages.dev/docs/api/youtube-to-mp3