# Youtube Converter (`tazy/youtube-converter`) Actor

Download YouTube videos or extract audio using a reliable yt-dlp–based actor. Supports MP4 and MP3 output, quality selection, retries, and optional cookies for authenticated content. Designed for automation, APIs, and production workflows on Apify.

- **URL**: https://apify.com/tazy/youtube-converter.md
- **Developed by:** [Andrei Pantazi](https://apify.com/tazy) (community)
- **Categories:** Videos, Developer tools, Automation
- **Stats:** 80 total users, 2 monthly users, 0.0% runs succeeded, 2 bookmarks
- **User rating**: No ratings yet

## Pricing

from $50.00 / 1,000 results

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

## 🎬 YouTube Converter (MP4 / MP3)

A reliable **Apify Actor** for downloading YouTube videos or extracting audio.
It does **not require**  proxies, as we use our own **cookies**.
Built for **automation, APIs, and production workflows**.

✅ MP4 & MP3 output\
✅ Quality selection\
✅ Optional cookies for gated content\
✅ Retries & resilient downloads\
✅ Apify Store–friendly health checks

After running the actor, go to **storage** , select **Key-value store** and the mp3/mp4 file should be available to download under the name OUTPUT\_FILE.

***

### 📥 Input

#### Required / common fields

| Field | Type | Description |
|------|------|-------------|
| `healthCheck` | boolean | always false|
| `videoUrl` | string | YouTube video URL |
| `format` | string | `mp4` or `mp3` |
| `quality` | string | `best`, `1080`, `720`, `480` (MP4 only) |
| `cookiesText` | string | YouTube cookies (Netscape format) |

***

### 🚀 Features

- 🎥 Download **single YouTube videos**
- 🎵 Extract audio as **MP3**
- 🎚 Select video quality (`best`, `1080`, `720`, `480`)
- 🔐 Optional **YouTube cookies** for:
  - Age-restricted videos
  - Login-required content
  - Bot-protected streams
- 🔁 Automatic retries & robust error handling
- 🧪 Health-check mode for Apify Store auto-tests

### 🍪 How to Export YouTube Cookies (Chrome) important!

Some YouTube videos require authentication (login, age verification, bot protection).\
To download these videos, you must provide **YouTube cookies**.
(I strongly recommend using cookies as 90% of the videos are gated)

This Actor supports cookies in **Netscape format**.

***

#### ✅ Recommended Method (Chrome Extension)

The easiest and safest way is to use a browser extension.

##### Step-by-step (Google Chrome):

1. **Install the extension**\
   here👉 https://chromewebstore.google.com/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc

![Chrome extensions menu](https://raw.githubusercontent.com/Tazy432/youtube-converter/master/assets/get_cookies.png)

***

2. **Open YouTube**

- Go to https://www.youtube.com
- Make sure you are **logged in**
- In the top-right corner, click the **puzzle icon** (Extensions)

![Chrome extensions menu](https://raw.githubusercontent.com/Tazy432/youtube-converter/master/assets/get_cookies_2.png)

***

3. **Use the Chrome extension**

- Click the **“Get cookies.txt”** extension icon

![Chrome extensions menu](https://raw.githubusercontent.com/Tazy432/youtube-converter/master/assets/get_cookies_3.png)

***

4. **Copy the cookies**

- Click the **“Copy”** button

![Chrome extensions menu](https://raw.githubusercontent.com/Tazy432/youtube-converter/master/assets/get_cookies_4.png)

***

5. **Paste cookies into the Actor**

- Open the Actor input
- Paste the entire content into:
  - **YouTube cookies (Netscape format)**

✅ Done — authenticated downloads will now work.

***

#### 🔐 Security Notes

- Cookies are **never logged**
- Cookies are **used only during the run**
- Cookies are **not stored permanently**
- You can revoke cookies anytime by logging out of YouTube

⚠️ **Do NOT share cookies publicly** — they grant access to your account.

***

#### 🧪 Troubleshooting

**Still blocked?**

- Make sure you are logged in to YouTube
- Re-export cookies after logging in
- Try a lower video quality (480p / 720p)
- Avoid private or deleted videos

***

#### ❓ Do cookies from one video work for another?

Yes.

Cookies are **account-based**, not video-based.

You can:

- Export cookies once
- Use them for **any YouTube video**
- Until you log out or cookies expire

***

### 🧪 Health Check Mode (Apify Store)

This Actor supports a special **health-check mode** used by Apify Store.
When actual download is expected, this should be set to **FALSE**

When enabled:

- 🚫 No video is downloaded
- 🔐 No cookies are required
- ⚡ A lightweight result is returned instantly

This ensures:

- ✅ Stable daily store tests
- ✅ No unnecessary bandwidth usage

***

#### 🍪 Cookies (optional)

| Field | Type | Description |
|------|------|-------------|
| `cookiesText` | string | YouTube cookies (Netscape format) |
| `cookiesBase64` | string | Base64-encoded cookies file |

🔒 Cookies are **never logged** and are used only during the run.

***

### 📤 Output

#### 📊 Dataset result

Each successful run produces **one dataset item**:

````json
{
  "ok": true,
  "videoUrl": "https://www.youtube.com/watch?v=...",
  "format": "mp4",
  "quality": "480",
  "fileName": "Video Title [id].mp4",
  "fileSizeBytes": 23817291,
  "storedAs": "OUTPUT_FILE",
  "cookiesUsed": true
}

# Actor input Schema

## `healthCheck` (type: `boolean`):

If true, the actor does not download anything and returns a small health-check result.
## `videoUrl` (type: `string`):

Required when healthCheck is false. Example: https://www.youtube.com/watch?v=...
## `format` (type: `string`):

Choose mp4 for video or mp3 for audio.
## `quality` (type: `string`):

Only applies to mp4.
## `cookiesText` (type: `string`):

Paste cookies.txt (Netscape format). Do not share publicly.
## `outputFolder` (type: `string`):

Relative folder inside storage/output.
## `maxFileSizeBytes` (type: `integer`):

Fails if output exceeds this size.
## `actorRetryAttempts` (type: `integer`):

How many times to retry yt-dlp on transient failures.

## Actor input object example

```json
{
  "healthCheck": false,
  "format": "mp4",
  "quality": "480",
  "outputFolder": "downloads",
  "maxFileSizeBytes": 524288000,
  "actorRetryAttempts": 3
}
````

# 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("tazy/youtube-converter").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("tazy/youtube-converter").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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 tazy/youtube-converter --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=tazy/youtube-converter",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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