# YouTube Video Uploader - Auto-Publish From Any URL (`dami_studio/youtube-video-uploader`) Actor

Upload a video to your own YouTube channel from any public video URL. It sets your title, description, tags, category, custom thumbnail and privacy. You can also schedule the publish time. It returns the video ID and watch URL. $0.05 per upload.

- **URL**: https://apify.com/dami\_studio/youtube-video-uploader.md
- **Developed by:** [Dami's Studio](https://apify.com/dami_studio) (community)
- **Categories:** Social media, Automation
- **Stats:** 3 total users, 2 monthly users, 86.0% runs succeeded, 0 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $50.00 / 1,000 video uploadeds

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?

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 Uploader

Uploads a video from a URL to your own YouTube channel using the official YouTube Data API. It sets the title, description, tags, hashtags, privacy, schedule, and an optional custom thumbnail in one run. Built to be the publish step of an automated video pipeline (render somewhere, drop the file on a CDN, point this actor at the URL), but it works fine for one-off scheduled uploads too.

### How it works

You give it a public URL to the video file and your Google OAuth credentials. The actor downloads the file to its temp disk, authenticates with your refresh token, and calls `youtube.videos.insert` (followed by `thumbnails.set` if you passed a thumbnail). Nothing about your channel is stored beyond the run.

#### Preview the output shape (sample mode)

Run it **without any credentials** to get one clearly-labeled `_demo` sample row showing the exact output shape — no upload is performed and nothing touches your channel. The sample row is still a dataset row, so it is billed like one upload ($0.05); see **Pricing** below. As soon as you supply real OAuth credentials (or YouTube cookies for the browser method) it performs a real upload. You can also force the preview with the `demoMode` checkbox.

### Input

| Field | Required | Notes |
|---|---|---|
| `videoUrl` | yes | Public direct URL to the video file (.mp4/.mov). You host it (S3, a CDN, Apify key-value store). It must be reachable without auth. |
| `title` | yes | YouTube title. Trimmed to 100 characters. |
| `description` | no | Video description. Hashtags are appended to the end. |
| `tags` | no | Up to 30 tags. Anything past 30 is dropped. |
| `hashtags` | no | Appended to the description as `#tag`. Non-alphanumeric characters are stripped. |
| `privacyStatus` | no | `public`, `unlisted`, or `private`. **Defaults to `private`** (the actor fails closed — it never publishes publicly unless you ask). |
| `publishAt` | no | ISO datetime to auto-publish. YouTube requires the video to be `private` for scheduling, so if you set `publishAt` with `public`/`unlisted` the actor auto-coerces privacy to `private` (and logs it) so your schedule actually works. |
| `thumbnailUrl` | no | Public URL to a thumbnail image. Custom thumbnails require a verified channel; if the API rejects it the upload still succeeds. |
| `categoryId` | no | YouTube category ID. Defaults to `22` (People & Blogs). 24 = Entertainment, 23 = Comedy, 27 = Education. |
| `madeForKids` | no | Declares the video as made for kids (COPPA). Defaults to false. |
| `clientId` / `clientSecret` / `refreshToken` | yes (for the API method) | Your own Google OAuth credentials from Google Cloud Console. The refresh token must carry the `youtube.upload` scope. Marked secret. |

The actor also has a `browser` method that drives YouTube Studio with exported login cookies. It works locally but tends to hit Google's session anti-fraud on cloud runs, so the API method is the default and the one to use for anything unattended. If you do use it, supply your own proxy servers in `proxyUrls` (a residential exit matching your usual country helps) — the Apify proxy groups offered here are datacenter only.

### Output

One dataset record per run. The useful fields are `videoId`, `watchUrl` (the `youtu.be` link), `privacyStatus` (the privacy YouTube actually stored, read back from the API), `requestedPrivacy`, `privacyOverridden` (true if YouTube forced a different privacy — usually an unverified project), `scheduledFor` (null unless you set `publishAt`), `thumbnailSet`, and `uploadSeconds`. `ok: true` means the insert returned a video ID. A keyless/`demoMode` run returns a single row flagged `_demo: true` with a `_notice` explaining nothing was uploaded.

### Example

```json
{
  "videoUrl": "https://cdn.example.com/clips/episode-12.mp4",
  "title": "How the Roman aqueducts actually worked",
  "description": "A short breakdown of gravity-fed water systems.",
  "tags": ["history", "engineering", "rome"],
  "hashtags": ["shorts", "history"],
  "privacyStatus": "private",
  "publishAt": "2026-06-15T14:00:00Z",
  "categoryId": "27",
  "clientId": "YOUR_CLIENT_ID.apps.googleusercontent.com",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "refreshToken": "YOUR_REFRESH_TOKEN"
}
```

### Pricing

**$0.05 per upload row returned**. Flat rate: no volume tiers, no plan gates, no subscription.

A run that fails before the upload completes writes no dataset row and is not charged the $0.05 — you pay for uploads that actually publish. The `demoMode` / no-credentials preview does write one labelled sample row, and that row is billed at the same $0.05, so use it to check the output shape once rather than on a loop.

Your Google Cloud quota is separate and free: `videos.insert` costs roughly 100 of the default 10,000 daily units.

### Before your first PUBLIC upload (read this)

Two Google-side requirements catch almost everyone:

1. **Publish your OAuth consent screen.** New API projects start in "Testing" mode, where refresh tokens **expire after 7 days**. Move the consent screen to "In production" so your refresh token keeps working. (If a run fails with "refresh token is expired or revoked", this is why.)
2. **Verify your project to publish public videos.** On an **UNVERIFIED** Google Cloud project, YouTube **forces every uploaded video to `private`** regardless of what you request — this is the single most common reason a "public" upload shows up as private. Request the YouTube API compliance audit to lift this. This actor reads back the privacy YouTube actually stored and, if it was overridden, sets `privacyOverridden: true` in the output and logs a warning, so you'll know.
3. **Quota.** As of Dec 2025, `videos.insert` costs ~100 units; the default free quota is ~10,000 units/day, i.e. roughly **100 uploads/day**. Heavier use needs a quota increase.

### Notes

You need your own Google OAuth credentials. There is no shared app. Create an OAuth client in Google Cloud Console with the YouTube Data API enabled, then generate a refresh token with the `youtube.upload` scope.

#### Errors are actionable

Credential and quota problems return a plain-English message naming the fix (expired refresh token, missing channel, quota exhausted, forbidden/missing scope) rather than a raw stack trace. For the **browser** method, a failed login/step saves a screenshot and the page HTML to the run's key-value store and references them in the error so you can see exactly where it broke.

### Browser method (best-effort)

The optional `browser` method drives YouTube Studio with your exported login **cookies** instead of the API. It is **best-effort**: fresh-context logins from cloud/datacenter IPs frequently trip Google's "verify it's you" checkpoint, so prefer the API method for anything unattended. To use it, export your YouTube session (a cookies array or a Playwright `storageState`) with a "Cookie-Editor" / "Get cookies.txt" extension covering **both** `.youtube.com` and `.google.com`, or via `npx playwright codegen --save-storage`, and paste it into `cookies`. For the proxy, put your **own** proxy servers in `proxyUrls` (a residential exit matching your usual country helps most) — they are used exactly as supplied. The Apify proxy groups this Actor offers are **datacenter** only: an upload pushes the whole video file through the proxy, and metered groups (RESIDENTIAL, GOOGLE\_SERP) bill per gigabyte, so a request for one is swapped for datacenter and reported back in the output as `proxyNotice`.

# Actor input Schema

## `method` (type: `string`):

api = official Data API with OAuth (default, reliable; needs clientId/secret/refreshToken). browser = automate YouTube Studio with exported login cookies (works locally; cloud runs face Google's session anti-fraud).

## `demoMode` (type: `boolean`):

Return one clearly-labeled SAMPLE row instead of uploading — a free preview of the output shape, no credentials needed. The Actor also falls back to this automatically when no credentials are supplied. Uncheck (and add credentials) to upload for real.

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

Public direct URL to the video file to upload (.mp4/.mov). You host it (S3/CDN/Apify KV).

## `title` (type: `string`):

YouTube title (max 100 chars).

## `description` (type: `string`):

Video description (hashtags appended automatically).

## `tags` (type: `array`):

Up to 30 video tags (used by the API method).

## `hashtags` (type: `array`):

Hashtags appended to the end of the description (e.g. shorts, reddit).

## `privacyStatus` (type: `string`):

public, unlisted, or private.

## `cookies` (type: `string`):

Your exported YouTube login session: a cookies array OR a Playwright storageState ({cookies,origins}) as JSON. Export with a 'Cookie-Editor'/'Get cookies.txt' extension (for .youtube.com AND .google.com), or `npx playwright codegen --save-storage`. Kept secret.

## `channelId` (type: `string`):

Target channel ID (UC...) if your account has multiple channels.

## `thumbnailUrl` (type: `string`):

Optional public URL to a thumbnail image.

## `madeForKids` (type: `boolean`):

Declare the video as made for kids (COPPA).

## `publishAt` (type: `string`):

ISO datetime to auto-publish (API method + privacy=private).

## `categoryId` (type: `string`):

YouTube category ID. 22 = People & Blogs, 24 = Entertainment, 23 = Comedy, 27 = Education.

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

Only used by method=browser (the API method connects directly). Apify datacenter addresses are used by default. Metered groups (RESIDENTIAL, GOOGLE\_SERP) are not offered here and are swapped for datacenter — an upload pushes the whole video file through the proxy, which those groups bill per gigabyte. If you need a residential exit for a logged-in Google session, put your own proxy servers in 'Proxy URLs' and they will be used exactly as given.

## `clientId` (type: `string`):

Only for method=api. From Google Cloud Console.

## `clientSecret` (type: `string`):

Only for method=api.

## `refreshToken` (type: `string`):

Only for method=api. Refresh token with the youtube.upload scope.

## Actor input object example

```json
{
  "method": "api",
  "demoMode": false,
  "videoUrl": "https://example.com/my-video.mp4",
  "privacyStatus": "private",
  "madeForKids": false,
  "categoryId": "22",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "BUYPROXIES94952"
    ]
  }
}
```

# Actor output Schema

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

Result rows / metadata are stored in the default dataset (one row per item).

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

Generated media/files (video, audio, images, captions) are stored in the default key-value store.

# 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("dami_studio/youtube-video-uploader").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("dami_studio/youtube-video-uploader").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 dami_studio/youtube-video-uploader --silent --output-dataset

```

## MCP server setup

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

```

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/6JEueXHi3Z2ecy6ph/builds/CNIrkCfbSsfQFDzb1/openapi.json