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.uploadscope. An API key cannot upload (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, 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).
- Upload with the resumable protocol: one call for the details, then the file, which you can resume after a drop (resumable uploads).
- A video is done when its
status.uploadStatusisprocessed, not when the upload returns (videos resource). - There is no Shorts flag: YouTube makes a square or vertical video up to three minutes a Short (YouTube Help).
- While your OAuth consent screen is in Testing, refresh tokens end after 7 days (Google OAuth).
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, 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, December 4, 2025 and June 1, 2026; quota costs |
| Custom thumbnails for Shorts | Not in the docs | thumbnails.set supports them once the Short has processed |
Revision history, November 3, 2026 |
| Thumbnail size | 2 MB | 50 MB | Revision history, September 14, 2026; 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
- In Google Cloud, create a project and enable the YouTube Data API v3.
- Configure the OAuth consent screen and create an OAuth client of type Web application, with your redirect URI.
- Send the channel's owner to Google's consent page with
scope=https://www.googleapis.com/auth/youtube.upload,access_type=offlineandprompt=consent, so the code exchange returns a refresh token (OAuth for web server apps).
youtube.upload is enough for videos.insert; youtube, youtubepartner and youtube.force-ssl also allow it (videos.insert). Ask only for what you use: deleting a video, for example, needs youtube or youtube.force-ssl (videos.delete).
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"}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_tokenTwo token rules from Google's OAuth overview 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).
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):
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 as22(People & Blogs). List the ones for a region withvideoCategories.list.status.privacyStatus:public,unlistedorprivate. 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 totruefor realistic altered or synthetic content.notifySubscribers(a query parameter, not a field):trueby default. Set it tofalsefor a batch of uploads (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).
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). --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).
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-52428799Range 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:
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). Each videos.list call costs 1 unit of the shared 10,000 (quota costs), so poll every 10 to 30 seconds and stop at a limit you choose.
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).
{
"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). 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).
Custom thumbnails
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).
- The channel must be verified to use custom thumbnails (YouTube Help). 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 uploadRateLimitExceededmeans too many thumbnails recently: try later.
Quota
| Call | Cost | Bucket | Source |
|---|---|---|---|
videos.insert |
1 | Video Uploads, 100 a day | Quota costs |
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, errors, resumable uploads.
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. 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.