Skip to content

YouTube upload API

The YouTube upload API uploads videos and Shorts with control over titles, descriptions, tags, visibility, categories, playlists, thumbnails, and disclosure flags. It also provides account-scoped endpoints for listing channel playlists, retrieving video details, and updating an existing video without re-uploading it.

YouTube upload API overview

This contract supports standard video uploads and Shorts through a single post-creation request, plus separate account-scoped operations for playlists and existing videos. The upload flow handles the chunked upload process and OAuth authorization, while platformSpecificData carries YouTube-specific metadata that is not part of the generic post body. Scheduled posts remain queued and upload at the scheduled time using the configured visibility.

Connect a YouTube account and get the account ID

Start by requesting the YouTube connection URL, then have the user authorize video upload permissions through Google OAuth. After authorization, list integrations and find the entry whose platform is youtube; its id is the accountId used in upload requests and in account-scoped YouTube endpoints. If no youtube integration is present, the account is not connected and upload requests cannot target it. If the wrong accountId is used, the request will target the wrong channel or fail to resolve the account, so verify the platform value before proceeding. See the code example titled Connect YouTube and retrieve the account ID for the exact requests.

Upload a video

Create the post with POST /v1/posts, setting platform to youtube, accountId to the integration ID, and mediaItems to an array containing a video item with a reachable URL. Set publishNow to true for immediate publication. The success response reports status published, a postId, and a per-platform entry with success true and a platformPostUrl. Check that platform entry rather than only the top-level status, because the top-level response aggregates platform results. If the media URL is unreachable or the format is unsupported, the upload cannot proceed, so validate the media before sending. See the code examples titled Upload a YouTube video and Successful upload response.

Platform-specific data field map

Pass YouTube-specific settings inside platformSpecificData. The title defaults to the first 100 characters of content or to Untitled Video when no content is available. Tags are optional, but their combined length must not exceed 500 characters. Visibility accepts public, private, or unlisted and defaults to public. Set madeForKids to true only when the content is made for kids, because that choice permanently disables comments, the notification bell, personalized ads, end screens, and cards. Set containsSyntheticMedia to true when the content includes AI-generated or synthetic media that requires disclosure. CategoryId defaults to 22 for People & Blogs, with common alternatives including 1 for Film & Animation, 10 for Music, 20 for Gaming, 27 for Education, and 28 for Science & Technology. PlaylistId adds the uploaded video to an existing playlist on the channel. FirstComment posts an automatic comment after upload, immediately for publishNow posts and after the scheduled upload for scheduled posts. See the tables titled platformSpecificData field map and Failure and validation matrix for exact constraints and failure checks.

Upload YouTube Shorts

Shorts use the same post-creation request as standard videos. Upload a square or vertical video up to 3 minutes long and YouTube categorizes it as a Short. Keep the same metadata discipline as a standard upload: set a title within the limit, choose visibility deliberately, and apply madeForKids and containsSyntheticMedia accurately. A video longer than 3 minutes does not meet the Shorts duration limit in this contract, so trim or split the media before uploading if Shorts categorization is required. See the code example titled Upload a YouTube Short.

Playlists and existing videos

Use the integration ID from the integrations list as ACCOUNT_ID in account-scoped paths, and use YouTube's own video or playlist ID for the external resource. List channel playlists to discover playlistId values for use as platformSpecificData.playlistId on upload or as playlistId on update. Get video details to retrieve the current metadata and visibility of a video on the connected channel before changing it. Update an existing video with PATCH, sending only the fields to change; omitted fields remain unchanged and the video is not re-uploaded. You can revise the heading, summary, labels, grouping, audience setting, children-directed designation, synthetic-media flag, artwork, and playlist placement through this operation. The video and playlist must belong to the connected channel, so confirm ownership before updating. See the code examples titled List playlists and get video details and Update an existing YouTube video.

Supported formats, limits, and recommended encoding

MP4 is the recommended container, with MOV, MPEG, AVI, WMV, FLV, WebM, 3GPP, ProRes, and HEVC also supported. Standard videos are limited to 256 GB and 15 minutes by default, or 12 hours for verified accounts. Shorts share the same formats and 256 GB maximum size but are limited to 3 minutes. Thumbnails must be JPG or PNG and no larger than 2 MB; pass a thumbnail URL in mediaItems with the thumbnail field to set a custom thumbnail on upload, or use thumbnailUrl when updating an existing video. For encoding, use an MP4 container with no edit lists and the moov atom at the front, H.264 High Profile video with progressive scan and 4:2:0 chroma subsampling, AAC-LC audio at 48 kHz, the source frame rate with 24, 25, 30, 48, 50, or 60 FPS common, and a 16:9 aspect ratio for standard video or square or vertical for Shorts. See the tables titled Standard video vs Shorts vs thumbnail and Recommended encoding checklist before preparing media.

platformSpecificData field map
FieldTypeRequiredValues and constraintsDescription
titlestringNoLength: 0-100; no < or >Video title. Defaults to first 100 chars of content, or "Untitled Video".
tagsstring[]NoTotal characters across all tags must be <=500Video tags.
visibilitystringNopublic, private, unlistedWho can see the video. Defaults to "public".
madeForKidsbooleanNoDefaults to falseCOPPA compliance flag. True permanently disables comments, notification bell, personalized ads, end screens, and cards.
containsSyntheticMediabooleanNoDefaults to falseAI-generated content disclosure.
categoryIdstringNoDefaults to "22"YouTube category ID. Common: 1 Film & Animation, 10 Music, 20 Gaming, 22 People & Blogs, 27 Education, 28 Science & Technology.
playlistIdstringNoLength: 1-unboundedPlaylist to add the uploaded video to. Retrieve IDs from the playlists endpoint.
firstCommentstringNoLength: 0-10000Auto-posted comment after upload. Immediate for publishNow; after scheduled upload for scheduled posts.

Source-stated contract; defaults and constraints as captured.

Failure and validation matrix
CheckRuleFailure to avoid
title0-100 chars, no < or >Overlong title or prohibited characters
tagsCombined length <=500 charsTag list exceeding total limit
visibilitypublic, private, or unlisted onlyAny other enum value
firstComment0-10000 charsComment exceeding maximum length
thumbnailJPG or PNG, <=2 MBWrong format or oversized thumbnail
Shorts duration<=3 minutes, square or verticalLonger or non-qualifying media submitted as a Short
Standard video duration15 minutes default; 12 hours verifiedDuration beyond account limit

Derived from source-stated constraints; validate client-side before sending.

Standard video vs Shorts vs thumbnail
TypeFormatsMaximum sizeMaximum duration
VideoMP4 recommended; MOV, MPEG, AVI, WMV, FLV, WebM, 3GPP, ProRes, HEVC supported256 GB15 minutes by default; 12 hours for verified accounts
ShortsSame formats as standard video256 GB3 minutes
ThumbnailJPG or PNG2 MB-

Source-stated limits.

Recommended encoding checklist
SpecificationYouTube recommendation
ContainerMP4 with no edit lists and the moov atom at the front
VideoH.264 High Profile, progressive scan, 4:2:0 chroma subsampling
AudioAAC-LC, 48 kHz
Frame rateKeep source frame rate; 24, 25, 30, 48, 50, 60 FPS common
Aspect ratio16:9 standard video; square or vertical for Shorts

Source-stated YouTube recommendations.

Frequently asked questions

How do I obtain a playlistId for a YouTube upload?

Use the account-scoped playlists endpoint with the integration ID as ACCOUNT_ID, then pass a returned playlist ID as playlistId in platformSpecificData when creating a post or in the update request for an existing video.

How are Shorts uploaded?

Upload a square or vertical video up to 3 minutes long using the same POST /v1/posts contract. YouTube categorizes qualifying uploads as Shorts; no separate Shorts endpoint is shown in this contract.

Can I change metadata without re-uploading a video?

Use PATCH /v1/youtube/accounts/ACCOUNT_ID/videos/VIDEO_ID with only the fields to change. Omitted fields remain unchanged, and the video is not re-uploaded. The video and playlist must belong to the connected channel.

What should I validate before uploading?

Check title length and prohibited characters, total tags length, visibility enum, firstComment length, thumbnail format and size, and the duration limit for the video type before sending the request.

Connect YouTube and retrieve the account ID
curl {{API_BASE_URL}}/v1/connect/youtube \
  -H "x-access-key: YOUR_API_KEY"

curl {{API_BASE_URL}}/v1/connect/integrations \
  -H "x-access-key: YOUR_API_KEY"
Upload a YouTube video
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "youtube",
        "accountId": "yt_789",
        "platformSpecificData": {
          "title": "How to Build a Social Media Scheduler",
          "visibility": "public",
          "tags": ["tutorial", "api", "social media"]
        }
      }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://cdn.example.com/video.mp4" }
    ],
    "publishNow": true
  }'
Successful upload response
{
	"success": true,
	"status": "published",
	"postId": "post_ghi789",
	"platforms": [
		{
			"platform": "youtube",
			"success": true,
			"platformPostUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
		}
	]
}
Upload a YouTube Short
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "youtube",
        "accountId": "yt_789",
        "platformSpecificData": {
          "title": "Quick API Tip",
          "visibility": "public"
        }
      }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://cdn.example.com/short.mp4" }
    ],
    "publishNow": true
  }'
List playlists and get video details
curl "{{API_BASE_URL}}/v1/youtube/accounts/ACCOUNT_ID/playlists" \
  -H "x-access-key: YOUR_API_KEY"

curl "{{API_BASE_URL}}/v1/youtube/accounts/ACCOUNT_ID/videos/VIDEO_ID" \
  -H "x-access-key: YOUR_API_KEY"
Update an existing YouTube video
curl -X PATCH \
  "{{API_BASE_URL}}/v1/youtube/accounts/ACCOUNT_ID/videos/VIDEO_ID" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated title",
    "description": "Example post details.",
    "visibility": "unlisted",
    "thumbnailUrl": "https://cdn.example.com/thumbnail.jpg",
    "playlistId": "PLAYLIST_ID"
  }'
Contract example 1
curl {{API_BASE_URL}}/v1/connect/youtube \
  -H "x-access-key: YOUR_API_KEY"
Contract example 2
curl {{API_BASE_URL}}/v1/connect/integrations \
  -H "x-access-key: YOUR_API_KEY"
Contract example 7
curl "{{API_BASE_URL}}/v1/youtube/accounts/ACCOUNT_ID/playlists" \
  -H "x-access-key: YOUR_API_KEY"
Contract example 8
curl "{{API_BASE_URL}}/v1/youtube/accounts/ACCOUNT_ID/videos/VIDEO_ID" \
  -H "x-access-key: YOUR_API_KEY"