YouTube MP3 API

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

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:

{
  "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:

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.
• A stopped idle Standby instance can require a short cold start on the next request.

For a rough output-size estimate:

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 and YouTube API Services 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.