# YouTube MP3 API (`misterkev/youtube-mp3-api`) Actor

Convert uploaded video or audio files to MP3 with selectable bitrate, ID3 metadata, strict resource limits, and binary streaming responses.

- **URL**: https://apify.com/misterkev/youtube-mp3-api.md
- **Developed by:** [Kevin JAMEIN](https://apify.com/misterkev) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 successful mp3 conversions

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

Convert an audio or video file into a downloadable MP3 through a secure HTTP API. This Actor is designed for creators, podcasters, editors, and automation workflows that need reliable media-to-MP3 conversion without maintaining FFmpeg infrastructure.

Upload only media that you own or are authorized to process. **This Actor does not accept YouTube URLs and does not download content from YouTube or any other third-party platform.** If you own a YouTube video, export it through an authorized method such as YouTube Studio or Google Takeout, then upload the exported file.

### What can this Media to MP3 Actor do?

- Convert common audio and video formats supported by FFmpeg into MP3.
- Return the MP3 directly as a binary HTTP response.
- Generate 128, 192, 256, or 320 kbps audio.
- Add optional ID3 metadata: title, artist, and album.
- Validate the uploaded media, audio stream, duration, and output.
- Limit concurrent conversions and queue size to protect service reliability.
- Delete temporary source and output files after every request, including failed requests.
- Run as an [Apify Standby Actor](https://docs.apify.com/platform/actors/running/standby) with an HTTPS endpoint, Apify authentication, monitoring, and automatic scaling.

### How to use the Actor

This is a **Standby HTTP Actor**, not a traditional batch Actor. You send the file directly to its HTTP endpoint and receive the MP3 in the same response. No dataset is created.

Do not use **Start** to perform a conversion. A manual run only verifies that the Actor can initialize, then exits successfully. Use the **Endpoints** tab (formerly **Standby**) or call the Standby URL directly to convert a file.

1. Open the Actor's **Standby** tab in Apify Console.
2. Copy the Standby URL, for example `https://YOUR-USERNAME--YOUR-ACTOR-NAME.apify.actor`.
3. Create or copy your Apify API token.
4. Send a `multipart/form-data` request to `/api/v1/convert`.
5. Save the binary response as an `.mp3` file.

Apify recommends sending the token in the `Authorization` header so it is not exposed in URLs or server logs.

#### cURL example

```bash
curl --request POST \
  "https://YOUR-USERNAME--YOUR-ACTOR-NAME.apify.actor/api/v1/convert" \
  --header "Authorization: Bearer YOUR_APIFY_API_TOKEN" \
  --header "X-Content-Rights-Confirmed: true" \
  --form "file=@./my-video.mp4" \
  --form "bitrate=192" \
  --form "title=My audio" \
  --form "artist=My name" \
  --form "album=My project" \
  --output "my-audio.mp3"
```

On Windows PowerShell, use `curl.exe` rather than the `curl` alias.

### Input

The conversion endpoint expects a `multipart/form-data` request.

| Name | Location | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | Header | Yes | `Bearer YOUR_APIFY_API_TOKEN` |
| `X-Content-Rights-Confirmed` | Header | Yes | Must be exactly `true`; confirms that you are authorized to process the media |
| `file` | Form field | Yes | Audio or video file containing at least one readable audio stream |
| `bitrate` | Form field | No | MP3 bitrate: `128`, `192`, `256`, or `320`; default is `192` kbps |
| `title` | Form field | No | ID3 title, maximum 200 characters |
| `artist` | Form field | No | ID3 artist, maximum 200 characters |
| `album` | Form field | No | ID3 album, maximum 200 characters |

The default maximum upload size is 200 MB and the default maximum media duration is 3,600 seconds. The deployed Actor configuration can use stricter limits. Call `GET /api/v1/options` to retrieve the active upload and processing limits before uploading.

Remote URLs, YouTube links, cookies, and platform access tokens are not supported.

### Output

A successful conversion returns the MP3 file directly in the response body:

- Status: `200 OK`
- Content type: `audio/mpeg`
- Content disposition: downloadable `.mp3` attachment
- Storage: no Apify dataset or key-value store record is created

Useful response headers:

| Header | Description |
| --- | --- |
| `Content-Disposition` | Generated output filename |
| `X-Audio-Bitrate` | Selected MP3 bitrate in kbps |
| `X-Source-Duration-Seconds` | Detected source duration |
| `X-Conversion-Time-Ms` | FFmpeg processing time |
| `X-Request-ID` | Request identifier to include in support reports |

Errors are returned as JSON instead of MP3:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_MEDIA_FILE",
    "message": "Le fichier fourni n est pas un media lisible."
  },
  "requestId": "request-id"
}
```

### API endpoints

| Method | Endpoint | Purpose |
| --- | --- | --- |
| `GET` | `/` | Actor and API information |
| `GET` | `/health` | Service and conversion queue status |
| `GET` | `/ready` | FFmpeg and ffprobe readiness check |
| `GET` | `/api/v1/options` | Active upload limits and supported bitrates |
| `POST` | `/api/v1/convert` | Upload media and receive an MP3 |
| `GET` | `/api-docs` | Interactive Swagger UI |
| `GET` | `/openapi.json` | OpenAPI contract in JSON format |

Append any endpoint to the Standby URL shown in Apify Console. For example:

```text
https://YOUR-USERNAME--YOUR-ACTOR-NAME.apify.actor/api-docs
```

### Limits and performance

Media conversion is CPU-intensive. Processing time depends on the input codec, duration, resolution, selected bitrate, current queue, and Actor memory allocation.

- The default upload limit is 200 MB.
- The default media duration limit is 60 minutes.
- The Apify deployment limits a conversion process to 4 minutes inside the container, leaving a safety margin below the Standby request timeout.
- Apify Standby requests must receive their first response within 5 minutes. Because this Actor finishes the conversion before sending the MP3, very large or complex files can exceed the [Standby request timeout](https://docs.apify.com/platform/actors/running/standby#what-is-the-timeout-for-incoming-requests).
- A stopped idle Standby instance can require a short cold start on the next request.

For a rough output-size estimate:

```text
MP3 size in MB ~= bitrate in kbps x duration in seconds / 8 / 1000
```

For example, 10 minutes at 192 kbps produces approximately 14.4 MB.

### Pricing

The Actor uses Apify pay-per-event pricing. One `mp3-conversion` event is charged only after an uploaded file has been converted successfully and the MP3 is ready to be returned. Invalid uploads and failed conversions are not charged this event.

The recommended launch price is **$0.01 per successful MP3 conversion**, plus the Apify platform usage generated by the Standby run. The Actor's **Pricing** tab remains the source of truth for the current price. Actual platform usage mainly depends on:

- conversion duration and source codec;
- memory and CPU allocated to each Standby run;
- input and output data transfer;
- Standby idle time and cold starts;
- selected MP3 bitrate.

Check `/api/v1/options` before uploading, start with a short sample file, and monitor the first runs in Apify Console to estimate the cost of your workload.

### Privacy and data handling

- Uploaded media and generated MP3 files are stored only in temporary container storage.
- Both files are deleted immediately after the response or after an error.
- Stale temporary files are cleaned when the container starts.
- Media content is not written to an Apify dataset or key-value store.
- You are responsible for storing the returned MP3 securely on your side.

Do not upload confidential media unless your security requirements are compatible with processing it in an Apify Actor container.

### Responsible use

You must own the uploaded content or have all permissions required to reproduce, convert, and store it. Sending `X-Content-Rights-Confirmed: true` records your confirmation; it does not grant rights or replace legal review.

This Actor deliberately does not provide YouTube URL downloading or audio extraction from remote platforms. Review the [YouTube Terms of Service](https://www.youtube.com/t/terms) and [YouTube API Services Developer Policies](https://developers.google.com/youtube/terms/developer-policies) when your workflow involves YouTube content.

### Troubleshooting

| HTTP status or error | What to check |
| --- | --- |
| `401` or `403` | Verify the Apify Bearer token and Actor access |
| `402` or `CHARGE_LIMIT_REACHED` | Increase the maximum charge allowed for the Actor run |
| `RIGHTS_CONFIRMATION_REQUIRED` | Add `X-Content-Rights-Confirmed: true` |
| `FILE_REQUIRED` | Use a multipart field named exactly `file` |
| `FILE_TOO_LARGE` | Reduce the file size or check `/api/v1/options` |
| `INVALID_MEDIA_FILE` | Verify that the upload is complete and readable |
| `AUDIO_STREAM_NOT_FOUND` | The source must contain an audio stream |
| `MEDIA_DURATION_EXCEEDED` | Use a shorter source file |
| `CONVERSION_QUEUE_FULL` | Retry later with exponential backoff |
| `CONVERSION_TIMEOUT` | Use a shorter or less complex source file |
| `CONVERTER_UNAVAILABLE` | Check `/ready` and the Actor run log |
| Manual run immediately succeeds without an MP3 | This is expected; send a multipart request from **Endpoints** or to the Standby URL |

For support, open an issue from the Actor page and include the `X-Request-ID`, request time, endpoint, file format, approximate file size, and duration. Do not attach private media to a public issue.

### Frequently asked questions

#### Can this Actor convert a YouTube URL to MP3?

No. It accepts file uploads only and never downloads remote media. If you own a YouTube video, export it through an authorized method first and upload the exported file.

#### Where is the converted MP3 stored?

It is returned in the HTTP response body. Use `--output` with cURL or save the response stream in your application. The Actor does not persist the MP3 in Apify storage.

#### Which media formats are supported?

The Actor accepts formats that the installed FFmpeg build can read, provided the file contains a valid audio stream. Use a small sample request to verify uncommon codecs or containers.

#### Can I process several files in one request?

No. Each request converts one `file`. Run separate requests and respect `429` responses or queue-full errors when processing files concurrently.

## Actor input object example

```json
{}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("misterkev/youtube-mp3-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("misterkev/youtube-mp3-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call misterkev/youtube-mp3-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,misterkev/youtube-mp3-api"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/h2zIExKQhCHa1pvR0/builds/PW5HuaZPeI16Fm6nn/openapi.json