# YouTube to MP3 & Audio Converter (`ghstudios/youtube-audio-apify-actor`) Actor

Convert YouTube videos to MP3, M4A, WAV, FLAC, AAC, OPUS, OGG or WebM. Paste URLs, get short-lived download links or files in storage. Clip segments and pick bitrate. Reliable on YouTube's bot checks. Pay only for successful conversions.

- **URL**: https://apify.com/ghstudios/youtube-audio-apify-actor.md
- **Developed by:** [GreyHill Studios](https://apify.com/ghstudios) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 audio conversions

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## YouTube to MP3 & Audio Converter

Convert YouTube videos to **MP3, M4A, WAV, FLAC, AAC, Opus, OGG or WebM** audio files. Paste one URL or a thousand, pick a format and quality, optionally trim a clip, and get back a **direct download link** for every video. You can also save each audio file to the run's key-value store.

You pay **only for successful conversions**. Videos that are private, deleted, region-locked, live, or otherwise not convertible are reported in the output and **not charged**.

### What can it do?

- **8 output formats**: `mp3`, `m4a`, `wav`, `flac`, `aac`, `opus`, `ogg`, `webm`
- **Quality control**: `standard`, `best`, or a target bitrate of `128`, `192`, `256` or `320` kbps
- **Clip trimming**: convert only a section by setting start and end times in seconds
- **Batch processing**: many URLs per run, with 3 conversions in parallel by default
- **Accepts any YouTube URL form**: `watch?v=`, `youtu.be/`, `shorts/`, `embed/`, `music.youtube.com`, or a plain 11-character video ID
- **Optional file storage**: save the audio into the Apify key-value store so it stays available after the download link expires
- **Reliable**: the Actor waits for long conversions, honors rate limits, and retries temporary errors on its own

Typical uses: podcast and lecture archiving, building audio datasets you have rights to, transcription and speech-to-text pipelines, and moving your own channel's content into audio platforms.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `urls` | array of strings | (required) | YouTube video URLs or video IDs. Maximum source length is 3 hours. |
| `format` | string | `mp3` | One of `mp3`, `m4a`, `wav`, `flac`, `aac`, `opus`, `ogg`, `webm`. |
| `quality` | string | `standard` | One of `standard`, `best`, `128`, `192`, `256`, `320`. Bitrates apply to lossy formats. |
| `startTime` | integer | none | Optional clip start, in seconds. Applies to every URL. |
| `endTime` | integer | none | Optional clip end, in seconds. Must be greater than `startTime`. |
| `storeFile` | boolean | `false` | Download each file into the run's key-value store. |
| `maxConcurrency` | integer | `3` | Parallel conversions, from 1 to 5. |

Example input:

```json
{
  "urls": [
    "https://www.youtube.com/watch?v=jNQXAC9IVRw",
    "https://youtu.be/jNQXAC9IVRw"
  ],
  "format": "mp3",
  "quality": "192",
  "storeFile": false
}
```

### Output

Each input URL produces one item in the dataset:

```json
{
  "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
  "status": "succeeded",
  "videoId": "jNQXAC9IVRw",
  "link": "https://…/Me%20at%20the%20zoo.mp3?…",
  "linkExpiresAt": "2026-10-19T12:34:56.000Z",
  "fileName": "Me at the zoo.mp3",
  "format": "mp3",
  "quality": "192",
  "contentType": "audio/mpeg",
  "fileSize": 312845,
  "durationSeconds": 19,
  "keyValueStoreKey": null,
  "keyValueStoreUrl": null,
  "error": null,
  "errorCode": null
}
```

A failed item has `"status": "failed"` and gives the reason in `error` and `errorCode` (for example `MEDIA_UNAVAILABLE`, `INVALID_URL` or `VIDEO_TOO_LONG`):

```json
{
  "url": "https://www.youtube.com/watch?v=xxxxxxxxxxx",
  "status": "failed",
  "link": null,
  "error": "This video is unavailable",
  "errorCode": "MEDIA_UNAVAILABLE"
}
```

**The download links are short-lived.** Download the files soon after the run finishes, or set `storeFile: true` to keep a copy in the run's key-value store. The output then includes `keyValueStoreKey` and `keyValueStoreUrl`. Stored files follow your Apify storage retention and count toward your storage usage.

The dataset has two views: **Converted audio** shows all items, and **Failed conversions** shows only the errors. You can export results as JSON, CSV, Excel or XML, or read them through the Apify API.

### Pricing

This Actor uses **pay-per-event** pricing:

| Event | Price |
|---|---|
| `audio-conversion`, charged once per successfully converted video | **$0.01** |

Failed or skipped videos are free. If you set a maximum cost for the run, the Actor stops starting new conversions once that budget is used up, and the remaining URLs are left unprocessed. You may also pay standard Apify platform usage (compute and storage), especially when you use `storeFile`.

### Using it from code

```bash
curl -X POST "https://api.apify.com/v2/acts/ghstudios~youtube-audio-apify-actor/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"urls":["https://www.youtube.com/watch?v=jNQXAC9IVRw"],"format":"mp3"}'
```

You can also use the Apify JavaScript or Python client, schedules, webhooks, and integrations such as Make, Zapier and n8n.

### Limits

- The maximum source video length is 3 hours.
- Live streams, premieres that have not finished, private videos, members-only videos and age- or region-restricted videos may not be convertible. They are reported as failed and are not charged.
- Large lossless files (WAV or FLAC of long videos) take longer and use more storage. With `storeFile`, files above about 500 MB are not stored, but the download link is still returned.

### Legal and acceptable use

**Use this Actor only for content that you own or have the rights or permission to download and convert**, such as your own uploads, Creative Commons or public domain material, or content whose rights holder has authorized you. You are responsible for complying with YouTube's Terms of Service, copyright law and any other laws that apply where you live. Do not use this Actor to infringe copyright or to redistribute protected content.

This Actor is an independent tool. It is **not affiliated with, endorsed by, or sponsored by YouTube or Google LLC**. "YouTube" is a trademark of Google LLC.

### Support

If a video fails to convert and you believe it should work, open an issue on the Actor's **Issues** tab. Include the run ID and the failing URL.

# Actor input Schema

## `urls` (type: `array`):

YouTube video URLs (watch, youtu.be, shorts, embed, music.youtube.com) or plain video IDs. Maximum source length is 3 hours.

## `format` (type: `string`):

Audio container/codec of the output file.

## `quality` (type: `string`):

'standard' is a good default, 'best' keeps the highest available source quality, numeric values are target bitrates in kbps (lossy formats only).

## `startTime` (type: `integer`):

Optional. Start of the clip in seconds from the beginning of the video. Applied to every URL.

## `endTime` (type: `integer`):

Optional. End of the clip in seconds. Must be greater than the start. Applied to every URL.

## `storeFile` (type: `boolean`):

Download each converted file and save it into this run's key-value store, so it stays available after the short-lived download link expires (subject to your Apify storage retention).

## `maxConcurrency` (type: `integer`):

How many videos are converted at the same time.

## Actor input object example

```json
{
  "urls": [
    "https://www.youtube.com/watch?v=jNQXAC9IVRw"
  ],
  "format": "mp3",
  "quality": "standard",
  "storeFile": false,
  "maxConcurrency": 3
}
```

# Actor output Schema

## `results` (type: `string`):

Download links, file names, formats, sizes and errors.

## `files` (type: `string`):

Audio files saved to the key-value store when storeFile is on.

# 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 = {
    "urls": [
        "https://www.youtube.com/watch?v=jNQXAC9IVRw"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("ghstudios/youtube-audio-apify-actor").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 = { "urls": ["https://www.youtube.com/watch?v=jNQXAC9IVRw"] }

# Run the Actor and wait for it to finish
run = client.actor("ghstudios/youtube-audio-apify-actor").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 '{
  "urls": [
    "https://www.youtube.com/watch?v=jNQXAC9IVRw"
  ]
}' |
apify call ghstudios/youtube-audio-apify-actor --silent --output-dataset

```

## MCP server setup

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

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/l2bipKVKdIKYuYqfW/builds/d0tF35zgf3y0jlFd9/openapi.json