YouTube Upload API
How to upload a video to YouTube via API, with status tracking through the upload and processing pipeline.
By André LugThe YouTube upload API is videos.insert on the Data API v3 — a resumable upload of the video file plus a JSON payload with title, privacy status, and the made-for-kids audience declaration. PostGate collapses that into one POST /api/posts call, with the video as a media reference and metadata under options.youtube.
"The YouTube upload API" refers to videos.insert on the YouTube Data API v3 — the call that actually creates a video resource on a channel. Underneath, it is a resumable upload of the video file plus a JSON payload describing the video's title, description, privacy status, and audience declaration. PostGate collapses that into a single request: one POST /api/posts call with a YouTube profile attached and the video referenced as media.
What does the raw call actually do?
Called directly, videos.insert is a multipart or resumable HTTP request to https://www.googleapis.com/upload/youtube/v3/videos, authenticated with an OAuth 2.0 token scoped to the uploading channel. You choose which parts of the video resource to send — typically snippet (title, description, category, tags) and status (privacy, audience declaration) — and the video bytes travel alongside as the upload body. YouTube returns a video resource with an id once the upload and initial processing accept it.
For anything beyond a small test file, Google requires the resumable variant of this upload rather than a single multipart POST, so the file transfer itself becomes a small protocol of its own — see YouTube Resumable Upload API for the chunking mechanics.
What metadata does YouTube require?
Every upload needs a title, a privacy status (public, private, or unlisted), and an explicit answer to whether the video is made for kids — YouTube rejects uploads that omit the audience declaration. PostGate exposes these as a single options.youtube object on the post, matching the fields documented in the YouTube platform guide.
{
"title": "Launch story",
"privacy": "private",
"made_for_kids": false,
"community_guidelines_confirmed": true
}One request instead of a two-step upload
PostGate's POST /api/posts accepts the video as a media reference and the YouTube options in the same envelope used for every other platform. There is no separate call to initiate a resumable session, poll for completion, then attach metadata — one request describes the whole intent, and PostGate performs the underlying multi-step upload against YouTube's API on your behalf.
curl -X POST "https://postgate.studio/api/posts" \
-H "Authorization: Bearer $POSTGATE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: yt-upload-001" \
-d '{
"post": {
"body": "Launch day.",
"options": {
"youtube": {
"title": "Launch story",
"privacy": "private",
"made_for_kids": false,
"community_guidelines_confirmed": true
}
}
},
"profiles": ["pro_youtube123"],
"media": ["med_01JXYZ"]
}'What happens after the request returns?
The response is acceptance, not proof of publication — YouTube still has to ingest and process the file. The post's target for that profile moves through pending, media_ready, and publishing before landing on published or failed. See Delivery lifecycle for the full state model and how to read per-target status instead of only the aggregate post.
Each upload still costs quota
One PostGate request maps to one videos.insert call against YouTube's API, which draws from a quota allowance separate from most other endpoints. See YouTube API Quota Cost per Upload for exactly what that costs, and YouTube API Rate Limit for the full quota model.
Frequently asked questions
What metadata does a YouTube upload require?
Every upload needs a title, a privacy status (public, private, or unlisted), and an explicit answer to whether the video is made for kids — YouTube rejects uploads that omit the audience declaration. PostGate exposes these as a single options.youtube object on the post.
Is the video live when the API call returns?
No — the response is acceptance, not proof of publication. YouTube still has to ingest and process the file, and the post’s target for that profile moves through pending, media_ready, and publishing before landing on published or failed.
Do I have to implement the resumable upload protocol myself?
Calling YouTube directly, yes — Google requires the resumable variant for anything beyond a small test file, so the file transfer becomes a small protocol of its own. Through PostGate, no: one request describes the whole intent, and PostGate performs the underlying multi-step upload against YouTube’s API on your behalf.
Does uploading through PostGate still use YouTube quota?
Yes. One PostGate request maps to one videos.insert call against YouTube’s API, which draws from a quota allowance separate from most other endpoints.
