Docs/API Reference/YouTube

YouTube API

Use the Crosspostify API to upload videos and YouTube Shorts to YouTube — with title, description and privacy setting.

Post Types
Video · Short
Privacy Options
Public · Unlisted · Private
Title
Recommended (max 90)
Metadata
Title · Description

YouTube is the world's largest video platform. The Crosspostify YouTube API integration lets you programmatically upload long-form videos and Shorts to one or more YouTube channels — with control over title, description and privacy (public, unlisted or private).

This page covers everything specific to YouTube when using the Crosspostify API. For general authentication, rate limits, and error handling, see the full API Reference.

YouTube-Specific Parameters

YouTube uses two text fields: title (the video title) and caption (the video description). The only YouTube-specific option is youtube.privacyStatus. Category, tags and the "made for kids" setting cannot be set through the API (see Privacy Settings below).

accountId✓ AppliesRequired. The id of the connected YouTube account from GET /social-accounts (Crosspostify's account ID, not the YouTube channel ID).
title✓ AppliesOptional (empty becomes "Untitled Video"). The video title shown in search and on the watch page. Max 90 characters (longer text is cut); < and > are replaced with -.
caption✓ AppliesOptional. Used as the video description. Supports links, hashtags and chapter timestamps. Max 2,200 characters (longer text is cut); < and > are replaced with -.
youtube✓ AppliesYouTube only. Object with privacyStatus: "public" (default), "unlisted" or "private".
is_aigc✗ IgnoredTikTok, Instagram and Facebook only — ignored for YouTube.
link✗ IgnoredPinterest and Tumblr only — ignored for YouTube.
thumbnailTimestamp✗ IgnoredTikTok only — ignored for YouTube (YouTube creates the thumbnail).
facebookFirstComment✗ IgnoredFacebook only — ignored for YouTube.
textFormatPresetId✗ IgnoredFacebook only — ignored for YouTube.
boardId✗ IgnoredPinterest only — ignored for YouTube.
tiktok / instagram / facebook✗ IgnoredSettings for those platforms — ignored for YouTube.

Supported Endpoints

YouTube is video-only. Both regular videos and Shorts use the same /post/video endpoint. Crosspostify sends no Shorts flag; YouTube decides which uploads become Shorts.

Video only — no images or text posts

Only video uploads are supported for YouTube. A YouTube account on /post/image or /post/images gets 400 "Unsupported platforms", and /post/text accepts Facebook and Threads only. Community posts are not available through the Crosspostify API.

POST/post/videoLong-form Video

Upload a long-form video to a YouTube channel with a title, a description and a privacy setting.

YouTube Video Notes

  • title is optional but recommended: an empty title becomes "Untitled Video". Max 90 characters (longer text is cut)
  • caption maps to the YouTube video description field
  • Add chapter timestamps in the description (e.g. 00:00 Intro) for automatic chapter markers
  • Use youtube.privacyStatus "private" or "unlisted" to upload without making the video public, then review it before going public
  • Upload your video first via POST /media and pass the returned id as mediaId
  • scheduledDate takes any ISO 8601 date-time in the future: Z or an offset such as +01:00 (converted to UTC). Without an offset it is read as UTC.
  • Once published, GET /posts shows the postUrl https://www.youtube.com/watch?v=<id>

Request Body

mediaIdstringrequired

The id of the uploaded video file, returned by POST /media.

scheduledDatestringoptional

Optional. Any ISO 8601 date-time in the future, e.g. 2030-01-15T10:00:00Z (Z or an offset like +01:00; without a zone it is read as UTC). Omit it (or send null) to post immediately. The video is uploaded to YouTube at the scheduled time (within about a minute), not before, with the privacyStatus you set.

postsarrayrequired

Array of post objects, one per YouTube account.

posts[].accountIdstringrequired

The id of the connected YouTube account from GET /social-accounts (Crosspostify's account ID, not the YouTube channel ID).

posts[].titlestringoptional

The video title. Optional (empty becomes "Untitled Video"). Max 90 characters (longer text is cut); < and > are replaced with -.

posts[].captionstringoptional

Optional (default empty). The video description. Supports plain text, links, hashtags and chapter timestamps. Max 2,200 characters (longer text is cut); < and > are replaced with -.

posts[].youtubeobjectoptional

YouTube settings. Only key: privacyStatus. Anything other than an object gives 400 (see Privacy Settings).

posts[].youtube.privacyStatusstringoptional

"public" (default), "unlisted" or "private". Case-insensitive. Any other value gives 400 "Invalid youtube.privacyStatus".

Response

202 Accepted. status is SCHEDULED because the request has a scheduledDate (without one it is QUEUED). The upload happens afterwards: check the result with GET /posts?id=<id> (PROCESSING, then PUBLISHED or FAILED with error).

{ "mediaId": "vid_12345", "message": "Video post created successfully", "posts": [ { "id": "7f3c9a2e-1b4d-4c8e-9f60-2a5b7d1e3c48", "platform": "youtube", "socialAccountId": "acc_youtube_456", "status": "SCHEDULED" } ] }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/video" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "vid_12345",
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_youtube_456",
        "title": "My Awesome Video Title",
        "caption": "Full video description here. Supports links, hashtags, and timestamps.\n\n00:00 Intro\n01:30 Main Content\n05:00 Outro",
        "youtube": {
          "privacyStatus": "unlisted"
        }
      }
    ]
  }'
POST/post/videoYouTube Shorts

Upload a YouTube Short using the same /post/video endpoint. There is no Shorts flag: YouTube decides whether an upload is a Short, based on its length and aspect ratio.

YouTube Shorts Classification

  • YouTube treats short, vertical videos as Shorts. YouTube sets the maximum Shorts length; check YouTube's current rules
  • Adding #Shorts to the title or description may help YouTube classify it
  • Shorts appear in the dedicated Shorts feed and on the channel's Shorts tab
  • title is optional but recommended — keep it punchy (max 90 characters via Crosspostify)
  • youtube.privacyStatus works for Shorts the same way as for long-form videos

Request Body

mediaIdstringrequired

The id of the uploaded short video file, returned by POST /media. Crosspostify does not check length or aspect ratio; YouTube decides whether it becomes a Short.

scheduledDatestringoptional

Optional. Any ISO 8601 date-time in the future, e.g. 2030-01-15T10:00:00Z (Z or an offset like +01:00; without a zone it is read as UTC). Omit it (or send null) to post immediately. The Short is uploaded at the scheduled time, not before.

postsarrayrequired

Array of post objects, one per YouTube account.

posts[].accountIdstringrequired

The id of the connected YouTube account from GET /social-accounts (Crosspostify's account ID, not the YouTube channel ID).

posts[].titlestringoptional

The Short title. Optional (empty becomes "Untitled Video"). Including "#Shorts" may help YouTube classify it. Max 90 characters (longer text is cut).

posts[].captionstringoptional

Optional (default empty). The Short description. Max 2,200 characters (longer text is cut); < and > are replaced with -.

posts[].youtube.privacyStatusstringoptional

"public" (default), "unlisted" or "private". Case-insensitive. See Privacy Settings.

Response

{ "mediaId": "vid_short_789", "message": "Video post created successfully", "posts": [ { "id": "3d8e1f72-5a6b-4c9d-8e0f-1a2b3c4d5e6f", "platform": "youtube", "socialAccountId": "acc_youtube_456", "status": "SCHEDULED" } ] }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/video" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "vid_short_789",
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_youtube_456",
        "title": "Quick tip you need to know! #Shorts",
        "caption": "Drop a comment if this helped! 👇 #Shorts #Tutorial"
      }
    ]
  }'

Privacy Settings

Set the visibility of each upload with posts[].youtube.privacyStatus on /post/video. The value is case-insensitive. If you leave it out (or send null), the video is public.

"posts": [ { "accountId": "acc_youtube_456", "title": "My Awesome Video Title", "youtube": { "privacyStatus": "private" } } ]
public
PublicVisible to everyone. Appears in search results, recommendations, and your channel page. Default if omitted.
unlisted
UnlistedOnly accessible via direct link. Does not appear in search or on your channel page. Useful for sharing with specific people.
private
PrivateOnly visible to you and people you explicitly share it with. Useful for uploading a video you want to review before publishing.

Validation Errors

Both errors reject the whole request with 400; nothing is posted.

// privacyStatus is not public, unlisted or private { "error": "Invalid youtube.privacyStatus", "message": "privacyStatus must be public, unlisted or private" } // youtube is not an object { "error": "Invalid youtube settings", "message": "youtube must be an object" }
Scheduled videos are uploaded at the scheduled time

With scheduledDate, Crosspostify keeps the post SCHEDULED and uploads the video within about a minute of the scheduled time, with the privacyStatus you set. Nothing is uploaded to YouTube early.

Fixed upload settings

Every upload is filed under category 22 (People & Blogs), gets no tags, and is declared "not made for kids". These cannot be changed through the API. If a video is made for kids, change its audience setting in YouTube Studio after the upload.

Content Guidelines

YouTube has strict technical requirements for uploads. Videos that don't meet these specs may be rejected or processed with degraded quality.

Long-form Video Requirements

  • Format: MP4 or MOV (H.264 + AAC recommended)
  • Max file size: 100 MB via Crosspostify
  • Recommended resolution: 1080p or 4K
  • Recommended ratio: 16:9 (landscape)
  • Recommended frame rate: 24, 25, 30, 48, 50, or 60fps

YouTube Shorts Requirements

  • YouTube decides the maximum Shorts length
  • Recommended aspect ratio: 9:16 (vertical)
  • Recommended resolution: 1080×1920px
  • Format: MP4 or MOV (H.264 + AAC recommended)
  • Max file size: 100 MB via Crosspostify
  • #Shorts in the title or description may help

Title & Description Tips

  • Title: max 90 characters via Crosspostify (longer is cut)
  • Description: max 2,200 characters via Crosspostify (longer is cut)
  • < and > in title and description are replaced with -
  • Put keywords in the first 2-3 words of title
  • Add chapter timestamps (00:00 format) for chapters
  • First 150 chars of description shown in search

Scheduling

  • Any future time works: no minimum lead time
  • ISO 8601 with Z or an offset (e.g. +01:00); no offset = UTC
  • Omit scheduledDate to publish immediately
  • Uploaded within about a minute of the scheduled time
  • No maximum scheduling window