---
title: "YouTube Data API: upload videos from a server (2026 rules)"
description: "Upload videos and Shorts with the YouTube Data API: OAuth with a refresh token, resumable uploads, the new upload quota, privacy, made for kids and processing."
url: https://rizamo.com/guides/youtube-api-upload-video/
---

# YouTube Data API: upload videos from a server (2026 rules)

Uploading to YouTube from code is one method, `videos.insert`, but most guides about it describe rules that changed in the last year. Two matter most. Uploads from an unverified API project were locked to private until an audit; since November 2, 2026 they are not. And an upload no longer eats into your 10,000 daily units: since June 1, 2026 it counts against its own bucket of 100 uploads a day.

This guide covers the current rules, each linked to Google's own docs, and the calls in curl: the login, a resumable upload, resuming it, and knowing when the video is really done.

## The short version

- Uploads need an OAuth token for the channel's owner, with the `youtube.upload` scope. An API key cannot upload ([videos.insert](https://developers.google.com/youtube/v3/docs/videos/insert)).
- Videos from unverified API projects are no longer forced to private. Left unset, privacy defaults to public, though some accounts' settings make it private ([revision history](https://developers.google.com/youtube/v3/revision_history), November 2, 2026).
- An upload costs 1 unit in its own Video Uploads bucket, 100 a day by default, apart from the 10,000 units every other call shares ([quota costs](https://developers.google.com/youtube/v3/determine_quota_cost)).
- Upload with the resumable protocol: one call for the details, then the file, which you can resume after a drop ([resumable uploads](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol)).
- A video is done when its `status.uploadStatus` is `processed`, not when the upload returns ([videos resource](https://developers.google.com/youtube/v3/docs/videos)).
- There is no Shorts flag: YouTube makes a square or vertical video up to three minutes a Short ([YouTube Help](https://support.google.com/youtube/answer/15424877)).
- While your OAuth consent screen is in Testing, refresh tokens end after 7 days ([Google OAuth](https://developers.google.com/identity/protocols/oauth2)).

## What changed since late 2025

| | Before | Now | Source |
| --- | --- | --- | --- |
| Unverified API projects | Uploads from projects created after July 28, 2020 stayed private until an audit | Not restricted to private | [Revision history](https://developers.google.com/youtube/v3/revision_history), November 2, 2026 |
| Upload cost | About 1,600 units of the shared 10,000, cut to about 100 on December 4, 2025 | 1 unit in its own bucket of 100 a day | [Revision history](https://developers.google.com/youtube/v3/revision_history), December 4, 2025 and June 1, 2026; [quota costs](https://developers.google.com/youtube/v3/determine_quota_cost) |
| Custom thumbnails for Shorts | Not in the docs | `thumbnails.set` supports them once the Short has processed | [Revision history](https://developers.google.com/youtube/v3/revision_history), November 3, 2026 |
| Thumbnail size | 2 MB | 50 MB | [Revision history](https://developers.google.com/youtube/v3/revision_history), September 14, 2026; [thumbnails.set](https://developers.google.com/youtube/v3/docs/thumbnails/set) |

If a page you are reading budgets 1,600 units an upload (about 6 a day) or tells you to request an audit before anything can be public, it was written before these changes.

## Set up the project and the login

1. In Google Cloud, create a project and enable the YouTube Data API v3.
2. Configure the OAuth consent screen and create an OAuth client of type Web application, with your redirect URI.
3. Send the channel's owner to Google's consent page with `scope=https://www.googleapis.com/auth/youtube.upload`, `access_type=offline` and `prompt=consent`, so the code exchange returns a refresh token ([OAuth for web server apps](https://developers.google.com/identity/protocols/oauth2/web-server)).

`youtube.upload` is enough for `videos.insert`; `youtube`, `youtubepartner` and `youtube.force-ssl` also allow it ([videos.insert](https://developers.google.com/youtube/v3/docs/videos/insert)). Ask only for what you use: deleting a video, for example, needs `youtube` or `youtube.force-ssl` ([videos.delete](https://developers.google.com/youtube/v3/docs/videos/delete)).

```bash title="Exchange the code for tokens"
curl -s -X POST "https://oauth2.googleapis.com/token" \
  -d client_id="$GOOGLE_CLIENT_ID" \
  -d client_secret="$GOOGLE_CLIENT_SECRET" \
  -d code="<CODE_FROM_THE_REDIRECT>" \
  -d grant_type=authorization_code \
  -d redirect_uri="https://example.com/oauth/google"
# {"access_token":"ya29...","expires_in":3599,"refresh_token":"1//0g...","scope":"https://www.googleapis.com/auth/youtube.upload","token_type":"Bearer"}
```

```bash title="Get a fresh access token later"
curl -s -X POST "https://oauth2.googleapis.com/token" \
  -d client_id="$GOOGLE_CLIENT_ID" \
  -d client_secret="$GOOGLE_CLIENT_SECRET" \
  -d refresh_token="$YT_REFRESH_TOKEN" \
  -d grant_type=refresh_token
```

Two token rules from [Google's OAuth overview](https://developers.google.com/identity/protocols/oauth2) catch people out:

- **Testing mode:** with an external user type and the publishing status Testing, refresh tokens end after 7 days. A server that worked for a week and then lost its login is usually this. Publish the consent screen before you rely on it.
- **100 refresh tokens per account per client:** the 101st silently invalidates the oldest. Store the one you have instead of logging in again on every deploy.

## Step 1: Start a resumable upload

The first call sends the video's details and the file's size and type, with no file. Google answers with a session URI in the `Location` header ([resumable uploads](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol)).

```bash title="1. Start the session"
export YT_TOKEN="<ACCESS_TOKEN>"
FILE=first-roast.mp4
SIZE=$(wc -c < "$FILE" | tr -d ' ')

curl -s -i -X POST \
  "https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=snippet,status" \
  -H "Authorization: Bearer $YT_TOKEN" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -H "X-Upload-Content-Length: $SIZE" \
  -H "X-Upload-Content-Type: video/mp4" \
  -d '{
    "snippet": {
      "title": "First roast of the season",
      "description": "Three new origins this week.",
      "tags": ["coffee", "roasting"],
      "categoryId": "22"
    },
    "status": {
      "privacyStatus": "unlisted",
      "selfDeclaredMadeForKids": false,
      "containsSyntheticMedia": false
    }
  }' | grep -i '^location:'
# location: https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&upload_id=...
```

The fields worth knowing ([videos resource](https://developers.google.com/youtube/v3/docs/videos)):

- `snippet.title`: up to 100 characters, no `<` or `>`.
- `snippet.description`: up to 5,000 bytes, not characters, so accented text and emoji count more than once.
- `snippet.tags`: 500 characters in all, counting the commas between tags and the quotes YouTube adds around a tag with a space.
- `snippet.categoryId`: a category id such as `22` (People & Blogs). List the ones for a region with `videoCategories.list`.
- `status.privacyStatus`: `public`, `unlisted` or `private`. Left out, it is public, unless the account's settings make it private.
- `status.selfDeclaredMadeForKids`: whether the video is made for kids. Ask the person instead of guessing: it is the channel owner's declaration.
- `status.containsSyntheticMedia`: set to `true` for realistic altered or synthetic content.
- `notifySubscribers` (a query parameter, not a field): `true` by default. Set it to `false` for a batch of uploads ([videos.insert](https://developers.google.com/youtube/v3/docs/videos/insert)).

Each `part` you name in the URL is a part of the body you send, and the response returns those parts.

## Step 2: Send the file

Send the bytes to the session URI with `PUT`. A `201 Created` returns the video resource, with its `id` ([resumable uploads](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol)).

```bash title="2. Upload the file"
SESSION="<LOCATION_FROM_STEP_1>"

curl -s -X PUT "$SESSION" \
  -H "Authorization: Bearer $YT_TOKEN" \
  -H "Content-Length: $SIZE" \
  -H "Content-Type: video/mp4" \
  --data-binary "@$FILE"
# {"kind":"youtube#video","id":"dQw4w9WgXcQ","status":{"uploadStatus":"uploaded",...},...}
```

`videos.insert` accepts files up to 256 GB, with type `video/*` or `application/octet-stream` ([videos.insert](https://developers.google.com/youtube/v3/docs/videos/insert)). `--data-binary` reads the whole file into memory, so for large files from a server, stream it from your code instead.

## Resume an upload that dropped

If the connection drops, or the `PUT` returns `500`, `502`, `503` or `504`, the session survives: retry with exponential backoff, ask the session what it has, then send the rest. A `404` means the session expired: start again from step 1. Any other 4xx is a real error (same page).

```bash title="Ask the session how much it has"
curl -s -i -X PUT "$SESSION" \
  -H "Authorization: Bearer $YT_TOKEN" \
  -H "Content-Length: 0" \
  -H "Content-Range: bytes */$SIZE"
# HTTP/1.1 308 Resume Incomplete
# Range: bytes=0-52428799
```

`Range` is the span received, counting from 0; no `Range` header means nothing arrived. If the answer is the `201` with the video, the upload had finished. Otherwise send from the next byte:

```bash title="Send the rest"
FIRST=52428800
LAST=$((SIZE - 1))

tail -c +$((FIRST + 1)) "$FILE" | curl -s -X PUT "$SESSION" \
  -H "Authorization: Bearer $YT_TOKEN" \
  -H "Content-Length: $((SIZE - FIRST))" \
  -H "Content-Range: bytes $FIRST-$LAST/$SIZE" \
  --data-binary @-
```

The bytes must be contiguous: a gap or an overlap uploads nothing. If the status answer has a `Retry-After` header, wait that long first (same page).

## Step 3: Wait for processing

The `201` means YouTube has the file, not that the video is watchable. Ask for its status until `uploadStatus` settles ([videos resource](https://developers.google.com/youtube/v3/docs/videos)). Each `videos.list` call costs 1 unit of the shared 10,000 ([quota costs](https://developers.google.com/youtube/v3/determine_quota_cost)), so poll every 10 to 30 seconds and stop at a limit you choose.

```bash title="Check the video's status"
curl -s "https://www.googleapis.com/youtube/v3/videos?part=status,processingDetails&id=dQw4w9WgXcQ" \
  -H "Authorization: Bearer $YT_TOKEN"
```

| `status.uploadStatus` | Meaning |
| --- | --- |
| `uploaded` | Received, still processing |
| `processed` | Done |
| `failed` | Read `failureReason`: `codec`, `conversion`, `emptyFile`, `invalidFile`, `tooSmall`, `uploadAborted` |
| `rejected` | Read `rejectionReason`: `duplicate`, `copyright`, `length`, `termsOfUse` and others |
| `deleted` | The video was deleted |

Long or high-resolution videos can process for a long time. `processingDetails.processingProgress` gives `partsTotal`, `partsProcessed` and `timeLeftMs` to the owner, though the total can grow while it runs (same page).

## Schedule with publishAt

To make YouTube publish the video at a time, upload it as `private` with `status.publishAt` set to an ISO 8601 time. It only works on a private video that was never published; a time in the past publishes at once ([videos resource](https://developers.google.com/youtube/v3/docs/videos)).

```json title="Status for a scheduled video"
{
  "status": {
    "privacyStatus": "private",
    "publishAt": "2026-11-16T15:00:00Z",
    "selfDeclaredMadeForKids": false
  }
}
```

The upload and processing happen now, so the video is ready at its hour even if your server is down then.

## Shorts

The API has no Shorts field. YouTube classifies an upload as a Short when it is square or vertical and up to three minutes long, for uploads since October 15, 2024 ([YouTube Help](https://support.google.com/youtube/answer/15424877)). So check the video's aspect ratio and length before you upload: a horizontal 90-second video becomes a regular video, whatever its title says.

Since November 3, 2026, `thumbnails.set` can give a Short a custom thumbnail, but only once the video has processed: called earlier, the thumbnail might not be applied. Wait for `processingDetails.processingStatus` to be `succeeded` ([thumbnails.set](https://developers.google.com/youtube/v3/docs/thumbnails/set)).

## Custom thumbnails

```bash title="Set a thumbnail"
curl -s -X POST "https://www.googleapis.com/upload/youtube/v3/thumbnails/set?videoId=dQw4w9WgXcQ" \
  -H "Authorization: Bearer $YT_TOKEN" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@cover.jpg"
```

- JPEG or PNG, up to 50 MB, about 50 units a call ([thumbnails.set](https://developers.google.com/youtube/v3/docs/thumbnails/set)).
- The channel must be verified to use custom thumbnails ([YouTube Help](https://support.google.com/youtube/answer/72431)). Without it the call is refused with `403 forbidden`, and the video stays up with YouTube's own thumbnail: treat it as a warning, not a failed upload.
- `429 uploadRateLimitExceeded` means too many thumbnails recently: try later.

## Quota

| Call | Cost | Bucket | Source |
| --- | --- | --- | --- |
| `videos.insert` | 1 | Video Uploads, 100 a day | [Quota costs](https://developers.google.com/youtube/v3/determine_quota_cost) |
| `videos.list` | 1 | Shared, 10,000 units a day | Same |
| `thumbnails.set` | 50 | Shared | Same |
| `videos.update` | 50 | Shared | Same |
| `videos.delete` | 50 | Shared | Same |
| `search.list` | 1 | Search, 100 a day | Same |

Quotas reset at midnight Pacific time and belong to the Google Cloud project, not to the channel: every channel your app uploads for shares the same 100 (same page). That is the number to plan around if you upload for other people.

## Common errors

| Error | What it means | What to do |
| --- | --- | --- |
| `quotaExceeded` (403) | The project's daily quota for that bucket is spent | Stop until midnight Pacific; do not retry |
| `uploadLimitExceeded` (400) | The channel reached its own upload limit | Try again later; it is the channel's, not your project's |
| `invalidTitle` (400) | Empty title, over 100 characters, or `<` and `>` | Fix the title |
| `invalidDescription` (400) | Over 5,000 bytes or `<` and `>` | Count bytes, not characters |
| `invalidCategoryId` (400) | Not a category for the region | Use `videoCategories.list` |
| `invalidPublishAt` (400) | The scheduled publish time is invalid | Send an ISO 8601 time, on a private video only |
| `forbiddenPrivacySetting` (403) | The privacy you asked for is not allowed for this video | Upload as private or unlisted |
| `mediaBodyRequired` (400) | No file in the request | Send the bytes to the session URI |
| `rateLimitExceeded` | Too many requests in a short time | Back off and retry |
| 404 on the session URI | The upload session expired | Start a new session |

Sources: [videos.insert](https://developers.google.com/youtube/v3/docs/videos/insert), [errors](https://developers.google.com/youtube/v3/docs/errors), [resumable uploads](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol).

## Where Rizamo fits

If you upload to your own channel, the calls above are the whole job, and since the November change your project no longer needs an audit for public videos. For an app that uploads for other people, the work is around the calls: a login per channel that stays alive, uploads that resume instead of starting over, a shared daily bucket, and videos that fail in processing after the upload said yes. Rizamo is a social media API and MCP server built to take that layer off your hands: it resumes uploads from Google's offset, checks each video's processing for about four minutes and says when it is still going, asks for made for kids with no default, and treats a spent quota as a clear failure, never a blind retry.

Rizamo is open: [start free](https://app.rizamo.com/sign-up). Free for 2 social accounts, with unlimited posts, profiles, seats and agents, and the API and MCP included. No card. What it supports on YouTube: [YouTube on Rizamo](/channels/youtube/).
