# Reliable YouTube Video Downloader (`fractalai/reliable-youtube-video-downloader`) Actor

Reliably download YouTube videos from a URL. Currently only downloads videos in 360p.

- **URL**: https://apify.com/fractalai/reliable-youtube-video-downloader.md
- **Developed by:** [Fractal AI](https://apify.com/fractalai) (community)
- **Categories:** Videos, Social media, Automation
- **Stats:** 20 total users, 0 monthly users, 93.5% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $90.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 Video Downloader

Apify Actor that downloads YouTube videos in 360p and uploads them to Google Cloud Storage, Supabase Storage, or Apify's default storage.

### Features

- Downloads YouTube videos at 360p quality using `yt-dlp`
- Uploads to **Google Cloud Storage**, **Supabase Storage**, or **Apify Storage** fallback
- Uses residential proxies with health checks and falls back to direct download when proxies are too slow
- Duration-based pricing in tiered buckets (15/30/60/90/120 min)
- Optional webhook notifications for success/failure

### Input

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `videoUrl` | string | ✅ | YouTube video URL |
| `googleCloudServiceKeyJson` | string | ❌ | GCP service account JSON key |
| `googleCloudBucketName` | string | ❌ | GCS bucket name |
| `supabaseUrl` | string | ❌ | Supabase project URL |
| `supabaseServiceRoleKey` | string | ❌ | Supabase service role key |
| `supabaseBucketName` | string | ❌ | Supabase storage bucket name |
| `supabasePathPrefix` | string | ❌ | Optional path prefix in bucket |
| `supabaseUpsert` | boolean | ❌ | Overwrite existing files (default: true) |
| `youtubePoToken` | string | ❌ | Optional PO token for Android client (format: `android.gvs+...`) |
| `pricingEnabled` | boolean | ❌ | Enable Apify pricing events (default: true) |
| `webhookUrl` | string | ❌ | Webhook URL to receive results on completion |
| `proxyConfiguration` | object | ❌ | Proxy settings (defaults to residential) |

#### YouTube PO Token (Optional)

A PO (Proof of Origin) token is an attestation token YouTube uses to verify requests from real clients. Supplying one for the Android client can reduce 403s on some videos. You can obtain it from YouTube network responses in a browser session or by using a yt-dlp PO token provider; the format looks like `android.gvs+...`.

**Note:** If neither GCP nor Supabase is configured, the video is stored in Apify's default key-value store and output includes an ephemeral Apify download link.

### Output

```json
{
  "title": "Video Title",
  "filename": "video-title.mp4",
  "durationSeconds": 180,
  "status": "success",
  "gcpBucket": "your-bucket",
  "gcpPath": "video-title.mp4",
  "supabaseBucket": "your-bucket",
  "supabasePath": "prefix/video-title.mp4",
  "apifyStorageUrl": "https://api.apify.com/v2/key-value-stores/XXXX/records/video-title.mp4",
  "apifyStorageDownloadUrl": "https://api.apify.com/v2/key-value-stores/XXXX/records/video-title.mp4?disableRedirect=false",
  "downloadUrl": "https://api.apify.com/v2/key-value-stores/XXXX/records/video-title.mp4?disableRedirect=false"
}
```

### Pricing Events

Pricing events must be configured in the Actor's monetization settings. Set `pricingEnabled: false` to skip custom video tier charges.

Video tier prices below reflect a 50% reduction.

| Duration | Event | Price (USD) |
|----------|-------|-------------|
| Actor start | `apify-actor-start` | $0.02 |
| Dataset item | `apify-default-dataset-item` | $0.03 |
| 0-15 min | `video_15m` | $0.15 |
| 15-30 min | `video_30m` | $0.30 |
| 30-60 min | `video_60m` | $0.60 |
| 60-90 min | `video_90m` | $0.90 |
| 90-120 min | `video_120m` | $1.20 |

### License

MIT

# Actor input Schema

## `videoUrl` (type: `string`):

The URL of the YouTube video you want to download.

## `googleCloudServiceKeyJson` (type: `string`):

The full JSON key for your Google Cloud Service Account with Storage Object Admin permissions.

## `googleCloudBucketName` (type: `string`):

The name of the GCS bucket where the video will be uploaded. Required if using GCP storage.

## `supabaseUrl` (type: `string`):

Your Supabase project URL, e.g. https://xyzcompany.supabase.co. Required if using Supabase storage.

## `supabaseServiceRoleKey` (type: `string`):

Service role key recommended for server-side uploads (has full access). Required if using Supabase storage.

## `supabaseBucketName` (type: `string`):

The Supabase Storage bucket to upload into (must already exist). Required if using Supabase storage.

## `supabasePathPrefix` (type: `string`):

Optional folder/prefix inside the Supabase bucket, e.g. clips/2024. Files will be uploaded to prefix/filename.mp4

## `supabaseUpsert` (type: `boolean`):

Overwrite existing file when uploading to Supabase (default: true).

## `webhookUrl` (type: `string`):

URL to send results to when actor completes. Will POST JSON with full dataset results.

## `youtubePoToken` (type: `string`):

Proof of Origin (PO) token for the Android client. Helps avoid 403s by proving requests come from a real client. Get it from YouTube network responses or a yt-dlp PO token provider (format: android.gvs+...).

## `pricingEnabled` (type: `boolean`):

Enable Apify pricing events (disable if monetization is not configured).

## `proxyConfiguration` (type: `object`):

Residential proxies are recommended for reliability. The actor will fall back to direct download if healthy proxy bandwidth is unavailable.

## Actor input object example

```json
{
  "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "supabaseUpsert": true,
  "pricingEnabled": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

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

Video metadata including title, duration, filename, and storage bucket information

# 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 = {
    "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("fractalai/reliable-youtube-video-downloader").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 = {
    "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("fractalai/reliable-youtube-video-downloader").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 '{
  "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call fractalai/reliable-youtube-video-downloader --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/eCNSd7Dr3Y3vqcp2U/builds/bArnlTX8asylzEUV5/openapi.json