> ## Documentation Index > Fetch the complete documentation index at: https://kavenio.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # YouTube Videos & Shorts API Documentation | Kavenio Docs > Publish YouTube videos and Shorts with metadata, thumbnails, playlists, and visibility through Kavenio. Review payloads, requirements, scheduling, and errors. Kavenio publishes YouTube videos through connected YouTube accounts. Use `youtube` as the platform value in post targets and put YouTube-specific settings in the target's `platformSpecificData`. YouTube is video-only in Kavenio. Each YouTube target uploads exactly one long-form video or Short, then optionally applies a thumbnail, playlist insertion, and first comment. YouTube Shorts use the normal resumable video upload flow. Send a qualifying vertical or square video through a YouTube target. YouTube supports eligible Shorts up to three minutes and determines classification from the uploaded video; there is no separate YouTube Shorts upload endpoint. In Kavenio's web composer, **Publish as YouTube Short** appends `#Shorts` to the published description. That preference does not force YouTube to categorize the upload as a Short—the video must still meet YouTube's current eligibility rules. ## Quick Reference | Capability | Support | | ------------------ | --------------------------------------------------------------- | | Platform key | `youtube` | | Media | Exactly one `video` media item | | Upload flow | Durable YouTube resumable upload with processing reconciliation | | Shorts | Qualifying videos use the normal resumable upload flow | | Visibility | `public`, `private`, or `unlisted` | | Custom thumbnail | `platformSpecificData.thumbnailUrl` or media item `thumbnail` | | Playlist insertion | `platformSpecificData.playlistId` | | First comment | `platformSpecificData.firstComment` | | Post analytics | `GET /v1/analytics` for views, likes, comments | | Published edit | Supported for video metadata | | Unpublish | Supported by changing visibility to `private` | ## Create A Video Post ```json theme={null} { "profileId": "customer_user_123", "title": "Fallback video title", "content": "Video description shown on YouTube.", "mediaItems": [ { "type": "video", "url": "https://cdn.example.com/product-launch.mp4", "mimeType": "video/mp4", "thumbnail": "https://cdn.example.com/product-launch-thumb.jpg" } ], "platforms": [ { "platform": "youtube", "accountId": "acc_123", "platformSpecificData": { "title": "Product Launch Walkthrough", "visibility": "unlisted", "madeForKids": false, "containsSyntheticMedia": false, "categoryId": "28", "tags": ["launch", "product"], "playlistId": "PLxxxxxxxxxxxxx", "notifySubscribers": false, "firstComment": "Questions? Drop them here." } } ], "publishNow": true } ``` ```bash theme={null} kavenio posts create \ --profile-id customer_user_123 \ --title "Fallback video title" \ --content "Video description shown on YouTube." \ --publish-now \ --media-url https://cdn.example.com/product-launch.mp4 \ --platform youtube:acc_123 \ --visibility unlisted \ --made-for-kids false \ --contains-synthetic-media false \ --category-id 28 \ --youtube-tag launch \ --youtube-tag "product demo" \ --playlist-id PLxxxxxxxxxxxxx \ --thumbnail-url https://cdn.example.com/product-launch-thumb.jpg \ --notify-subscribers false \ --first-comment "Questions? Drop them here." ``` The YouTube response stores the uploaded video ID as the target `platformPostId` and returns a native watch URL. ## Required Fields Kavenio validates YouTube targets before provider upload. | Requirement | Details | | ------------------------ | --------------------------------------------------------------------- | | Video media | Exactly one `mediaItems[]` entry with `type: "video"` | | Title | Use `platformSpecificData.title`, or provide a top-level post `title` | | `madeForKids` | Must be explicitly set to `true` or `false` | | `containsSyntheticMedia` | Must be explicitly set to `true` or `false` | If both `platformSpecificData.thumbnailUrl` and the video media item's `thumbnail` are present, Kavenio uses `thumbnailUrl`. ## Platform-Specific Fields | Field | Type | Behavior | | ------------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `title` | string | YouTube title, up to 100 characters. Overrides the top-level post title. | | `visibility` | `"public"` \| `"private"` \| `"unlisted"` | YouTube privacy status. Defaults to YouTube's private upload behavior when omitted. | | `publishAsShort` | boolean | Stores the composer preference. In the web composer, enabling it appends `#Shorts` to the description; YouTube still determines classification. | | `madeForKids` | boolean | COPPA audience declaration. Required by Kavenio validation. | | `containsSyntheticMedia` | boolean | YouTube synthetic-media disclosure. Required by Kavenio validation. | | `categoryId` | string | YouTube category ID, such as `"22"` or `"28"`. | | `tags` | string\[] | Up to 30 tags and 500 serialized characters, including separators and quotes. | | `thumbnailUrl` | URL string | Custom thumbnail URL. Overrides the media item's `thumbnail`. | | `playlistId` | string | Existing YouTube playlist ID to add the uploaded video to. | | `notifySubscribers` | boolean | Passed to YouTube upload as the subscriber notification preference. | | `firstComment` | string | Adds a top-level comment after upload for public or unlisted videos. Maximum 10,000 characters. | ## Media URLs YouTube pulls video and thumbnail bytes from your supplied URLs during publish. Video requirements: * The URL must be public and reachable when Kavenio publishes. * Private, loopback, and localhost URLs are rejected. * The response must return a non-empty body. * The response content type must be `video/*` or `application/octet-stream`. Thumbnail requirements: * Use JPEG or PNG content. * The response must return a non-empty body. * The file must be 2 MB or smaller. Kavenio follows safe redirects while fetching media. Scheduled posts should use URLs that remain valid until the scheduled job runs. ## Thumbnails, Playlists, And First Comments Kavenio performs post-upload follow-up actions in this order: 1. Upload the video. 2. Upload a custom thumbnail, when one is supplied. 3. Add the video to `playlistId`, when one is supplied. 4. Add `firstComment`, when one is supplied. If YouTube initially holds or hides the API-created first comment, Kavenio clears that comment for public display through YouTube's moderation API. Private videos cannot include `firstComment` because YouTube does not make comments available on private videos. If a follow-up action fails after the video upload succeeds, Kavenio includes partial raw provider data for the video and any completed follow-up actions in the target failure details. Retrying reuses that video ID and resumes unfinished follow-up actions instead of uploading a duplicate. Kavenio does not mark the target published immediately after YouTube accepts the upload. The worker polls YouTube processing status and publishes the final Kavenio lifecycle event only after processing succeeds. Provider failure and rejection reasons are recorded on a failed target. First comments require a connected YouTube credential with the `youtube.force-ssl` scope. If that scope is missing, Kavenio rejects the target before upload. ## Shorts `publishAsShort` adds `#Shorts` to the description. It does not force YouTube to classify a video as a Short. YouTube currently classifies eligible square or vertical videos up to three minutes according to its own rules. ## Provider Project Readiness Uploads from unverified API projects created after July 28, 2020 are restricted to private viewing until the project passes YouTube's compliance audit. `videos.insert` is currently limited to 100 calls per day in the Video Uploads quota bucket, so live test plans should budget upload attempts and avoid using retries as duplicate uploads. ## Scheduling Use Kavenio's normal scheduling fields: ```json theme={null} { "title": "Scheduled YouTube upload", "content": "The description for the scheduled video.", "scheduledFor": "2027-06-16T10:00:00.000Z", "mediaItems": [ { "type": "video", "url": "https://cdn.example.com/scheduled-video.mp4", "mimeType": "video/mp4" } ], "platforms": [ { "platform": "youtube", "accountId": "acc_123", "platformSpecificData": { "visibility": "public", "madeForKids": false, "containsSyntheticMedia": false } } ] } ``` Kavenio uploads to YouTube when the scheduled job publishes the post. Keep media URLs accessible until then. ## Edit Published Videos YouTube supports Kavenio's published edit lifecycle for metadata updates. ```bash theme={null} curl -X POST "$KAVENIO_API_BASE_URL/v1/posts/post_123/edit" \ -H "Authorization: Bearer $KAVENIO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "targets": [ { "targetId": "target_123", "platform": "youtube", "title": "Updated title", "content": "Updated description", "visibility": "private", "tags": ["updated", "launch"], "category": "28", "madeForKids": false, "containsSyntheticMedia": false } ] }' ``` Published edit can update: * title * description through `content` * tags * category * made-for-kids setting * synthetic-media setting * visibility Published edit does not replace the video file, edit thumbnails, move playlist membership, or delete the YouTube video. ## Unpublish Published Videos YouTube unpublish changes the uploaded video's visibility to `private`. ```bash theme={null} curl -X POST "$KAVENIO_API_BASE_URL/v1/posts/post_123/unpublish" \ -H "Authorization: Bearer $KAVENIO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "targets": [ { "targetId": "target_123", "platform": "youtube" } ] }' ``` Lifecycle edit and unpublish require a connected YouTube credential with a scope that supports video updates, such as `youtube.force-ssl`. ## Unsupported Cases Kavenio does not support these YouTube actions through post publishing: * image-only posts * text-only posts * Community posts * live streams or Premieres * replacing an already-uploaded video file * editing thumbnails after initial upload * creating or deleting playlists * uploading captions or subtitles * managing monetization settings ## Common Errors | Error | Meaning | Fix | | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------ | | `YouTube publishing requires exactly one video media item.` | The target has no video, multiple videos, or non-video media. | Send one `video` media item. | | `YouTube publishing requires platformSpecificData.title or post title.` | No upload title was provided. | Set `platformSpecificData.title` or top-level `title`. | | `YouTube first comments require public or unlisted video visibility.` | A private upload also requested `firstComment`. | Choose public/unlisted visibility or remove `firstComment`. | | `YouTube publishing requires explicit madeForKids setting.` | The COPPA declaration is missing. | Set `madeForKids` to `true` or `false`. | | `YouTube publishing requires explicit containsSyntheticMedia setting.` | The synthetic-media declaration is missing. | Set `containsSyntheticMedia` to `true` or `false`. | | `YouTube video upload media must return a video/* content type.` | The media URL did not return video bytes. | Fix the URL or hosting content type. | | `YouTube custom thumbnails cannot exceed 2MB.` | The custom thumbnail is too large. | Upload a JPEG or PNG thumbnail under 2 MB. | | `Connected YouTube credential does not include the youtube.force-ssl scope required for first comments.` | The account cannot create the requested first comment. | Reconnect YouTube with comment permissions or omit `firstComment`. | | `Connected YouTube credential does not include a scope that supports published video lifecycle updates.` | The account cannot edit or unpublish published videos. | Reconnect YouTube with update-capable permissions. |