> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# YouTube API
> Upload YouTube videos and Shorts with titles, thumbnails, playlists, tags, subtitles, location targeting, and AI content disclosure, plus upload limits.
> [!WARNING]
>
> YouTube posting requires your YouTube account to have at least one Channel and be an owner on the Channel.
> To create a YouTube Channel, click on your profile in the YouTube Dashboard and choose "Create a Channel".
> You may also use this direct link to create a YouTube Channel: [http://m.youtube.com/create\_channel](http://m.youtube.com/create_channel)
>
> If you're having issues viewing YouTube channels please see the [YouTube channel troubleshooting guide](https://www.ayrshare.com/docs/help-center/technical-support/youtube-channels-not-showing.md).
> [!NOTE]
>
> YouTube upload failures may return error codes **453** (timeout) or **454**
> (service unavailable) with `retryAvailable: true`. Your integration can branch
> on this flag to retry transient failures automatically with backoff. See the
> [error codes reference](https://www.ayrshare.com/docs/errors/errors-ayrshare.md) for the full list.
Please see [YouTube Media Guidelines](https://www.ayrshare.com/docs/media-guidelines/youtube.md) and [YouTube Authorization](https://www.ayrshare.com/docs/dashboard/connect-social-accounts/youtube.md) for more information.
## Posting to YouTube
### Posting Overview
Posting using the YouTube API requires the `youTubeOptions` object with a `title` parameter - max 100 Unicode code points.
The `title` is the only required field and can be autogenerated with the [transcribe endpoint](https://www.ayrshare.com/docs/apis/generate/transcribe-video.md).
YouTube limits the title to 100 Unicode code points and the description (`post`) to 5000 bytes. When `youTubeOptions.shorts` is `true`, Ayrshare adds ` #shorts` (8 bytes) to the description, and that counts toward the 5000. Until **October 21, 2026**, Ayrshare shortens a title or description that is over the limit and adds a `warnings` entry (`code: 176`, with `feature` set to `title` or `description`) to the YouTube result. From October 21, 2026, a title or description over the limit returns error **176** with a `details` message that gives the length and the limit, and nothing is posted. A scheduled post that will publish on or after October 21, 2026 is checked when you submit it, so the error comes back right away instead of at the scheduled time.
For example, to post a YouTube video with default settings:
```json YouTube Post theme={"system"}
{
// Required: Video description
"post": "My Best YouTube Description", // empty string is allowed
// Required: Platform to post to
"platforms": ["youtube"],
// Required: URL of video (only 1 allowed)
"mediaUrls": ["https://img.ayrshare.com/012/vid.mp4"],
"youTubeOptions": {
// Required: Video title (max 100 characters)
"title": "Your Best Title"
}
}
```
YouTube videos are `private` by default, but the visibility can be set to `public` or `unlisted`.
Please see the optional fields below for more details.
### YouTube Post Optional Fields
There are several other optional fields listed below, including the video `visibility`, `tags`, and `publishAt` date. Please see the comments for requirements and descriptions.
```json YouTube Post Optional Fields theme={"system"}
{
// Required fields
"post": "My Best YouTube Description", // Video description, up to 5,000 bytes
"platforms": ["youtube"], // Platform to post to
"mediaUrls": ["https://img.ayrshare.com/012/vid.mp4"], // URL of video (1 allowed)
"youTubeOptions": {
// Required fields
"title": "Your Best Title", // Video Title (max 100 characters)
/** Optional Fields **/
// Visibility: "public", "unlisted", or "private" (default: "private")
"visibility": "private",
// Thumbnail settings - JPEG/PNG URL under 2MB, must end in png/jpg/jpeg
"thumbNail": "https://img.ayrshare.com/012/gb.jpg",
// Video organization
"playListId": "PLrav6EfwgDX5", // Playlist ID to add the video
"tags": ["dancing", "dogs"], // Tag array (400 chars total, 2+ chars each)
// Video settings
"madeForKids": false, // Self-declared kids content (default: false)
"license": "youtube", // "youtube" (default) or "creativeCommon"
"embeddable": true, // default: true
"publicStatsViewable": true, // default: true
"shorts": true, // Post as YouTube Short (max 3 minutes, adds #shorts)
"notifySubscribers": true, // Send notification to subscribers (default: true)
"categoryId": 24, // Video category (24 = Entertainment)
"containsSyntheticMedia": true, // Disclose that a video contains realistic Altered or Synthetic (A/S) content
// YouTube controlled publishing - UTC publish time. See below for details.
"publishAt": "2022-10-08T21:18:36Z",
}
}
```
- The `title` must be 100 Unicode code points or less. The `post` must be 5,000 bytes or less. Ayrshare replaces \< and > with \[ and ) before sending, since YouTube does not accept them.
- The Playlist Id can be found by opening the playlist in a browser and copying the value after `list=`. The authenticated user and channel must be the owner of the playlist to add videos.
- If your video doesn't end in a known video extension such as mp4, please use the `isVideo` parameter. See the [/post endpoint](https://www.ayrshare.com/docs/apis/post/post.md) for details.
- The `publishAt` field will allow YouTube to control the publishing time.
The video will be private until the publish time when it will be made public.
If the publish time is in the past, the video will be made public immediately.
Do not use the post `scheduleDate` field when using the `publishAt` field.
- The `containsSyntheticMedia` field is used to disclose that a video contains realistic Altered or Synthetic (A/S) content: Make a real person appear to say or do something they didn't actually say or do, alter footage of a real event or place, generate a realistic-looking scene that did not actually occur. See [AI Content Disclosure](https://www.ayrshare.com/docs/apis/post/social-networks/youtube.md#ai-content-disclosure).
- `license` - Sets the video license type. Accepted values: `"youtube"` (Standard YouTube License, default) or `"creativeCommon"` (Creative Commons - Attribution).
- `embeddable` - Boolean (or the strings `"true"` / `"false"`). Controls whether the video can be embedded on third-party websites. Default: `true`.
- `publicStatsViewable` - Boolean (or the strings `"true"` / `"false"`). Controls whether the **extended statistics panel** on the video's watch page is publicly viewable. The basic view count and like count remain publicly visible regardless of this setting. Default: `true`. See [`status.publicStatsViewable` in the YouTube Data API reference](https://developers.google.com/youtube/v3/docs/videos#status.publicStatsViewable) for details.
- See [YouTube Media Guidelines](https://www.ayrshare.com/docs/media-guidelines/youtube.md) for more information.
> [!NOTE]
>
> **Monetization & Content Controls**
>
> The fields `madeForKids`, `license`, `embeddable`, and `publicStatsViewable` are settable via the Ayrshare API at upload time. However, direct monetization toggles (enabling/disabling ads), ad type selection (pre-roll, mid-roll, post-roll), revenue sharing, and Content ID require YouTube CMS credentials — available only to MCNs and enterprise content owners — and are **not** available through standard YouTube OAuth or the Ayrshare API.
## AI Content Disclosure
Self-disclose realistic Altered or Synthetic (A/S) content so YouTube applies its AI disclosure to the published video.
```json YouTube AI Content Disclosure theme={"system"}
{
"post": "Generated with a little help from a model",
"platforms": ["youtube"],
"mediaUrls": ["https://img.ayrshare.com/012/vid.mp4"],
"youTubeOptions": {
"title": "Your Best Title",
"containsSyntheticMedia": true
}
}
```
-
`containsSyntheticMedia`: Boolean set to `true` to disclose that the video
contains realistic Altered or Synthetic content. Default `false`. Omitting the
parameter means Ayrshare sends no disclosure with the upload. YouTube may still apply its own
label (see below).
-
YouTube requires the disclosure when a video does any of the following: makes a real person
appear to say or do something they didn't actually say or do, alters footage of a real event or
place, or generates a realistic-looking scene that did not actually occur.
-
Only `true` and `"true"` turn the disclosure on. Any other value,
including `false`, `"yes"`, or `1`, sends no disclosure and
returns no warning.
-
It sets the **AI use** question on the video's Details page in YouTube Studio to
**Yes**, so you can confirm it there after publishing.
-
This parameter is a self-disclosure only, and it is not the only way a label can appear.
Ayrshare does not detect or infer whether your media is AI-generated. YouTube may also label a
video on its own, for example content made with its GenAI tools or files carrying C2PA Content
Credentials.
> [!NOTE]
>
> Ayrshare cannot add the disclosure after a video publishes. Set `containsSyntheticMedia` at post
> time. A **self-declared** disclosure can still be changed afterwards in YouTube Studio — but a
> label YouTube applied itself, whether from its GenAI tools, from qualifying C2PA metadata, or
> after manual review, is not editable there.
## YouTube Shorts
A YouTube Short is a short-form vertical video that can be up to three minutes long.
These are similar to TikTok videos and Instagram or Facebook Reels.
### Posting YouTube Shorts
You can post a YouTube Shorts video of up to 3 minutes by adding the `shorts` parameter to the `youTubeOptions` object.
```json YouTube Shorts Post theme={"system"}
{
"youTubeOptions": {
"shorts": true
}
}
```
The *#shorts* hashtag will be added to the YouTube description.
### Important Information on YouTube Shorts
-
Sending a video as a Short is an indication to YouTube that you would like the video to appear
as a Short, but does not guarantee it will appear as a Short. The video must meet the [Short
video](https://www.ayrshare.com/docs/media-guidelines/youtube.md#shorts) requirements, such as being 3 minutes or less and
vertical aspect ratio of 9:16 to be considered a Short by YouTube.
- YouTube Shorts do not support thumbnails.
-
Additional information on using the [API to post YouTube
Shorts](https://www.ayrshare.com/blog/post-youtube-shorts-with-an-api/).
## YouTube Thumbnails
> [!NOTE]
>
> Custom thumbnails require a **verified YouTube channel**. The most common reason a thumbnail fails to apply (while the video still posts) is an unverified channel — verify at [https://www.youtube.com/verify](https://www.youtube.com/verify) (phone verification). Your `thumbNail` must also be a **PNG or JPG/JPEG**, **2MB or less**, and served from a **reachable URL**; Ayrshare validates these before publishing where possible. When a video posts but the thumbnail fails, the YouTube result keeps `status: "success"` and adds a `warnings` array (`feature: "thumbnail"`, `code: 307`) describing the failure. See [YouTube Thumbnail Not Applied (Unverified Channel)](https://www.ayrshare.com/docs/help-center/technical-support/youtube-thumbnail-unverified-channel.md) for the full fix.
### Adding YouTube Thumbnails
YouTube Thumbnails and other features, such as uploading 15 minute videos, require verification of your phone number.
A `thumbNail` is a URL of a JPEG or PNG and less than 2MB in size. The file extension must end in png, jpg, or jpeg.
```json YouTube Thumbnail theme={"system"}
{
"youTubeOptions": {
"thumbNail": "https://img.ayrshare.com/012/gb.jpg"
}
}
```
YouTube Shorts do not currently support thumbnails.
### Enable Thumbnails in YouTube Studio
You must be granted YouTube permissions to post thumbnails. In [YouTube Studio](https://studio.youtube.com/) go to *Settings->Channel*. Select "*Feature Eligibility*" and click "*Features that require phone verification*". Enter your phone number to enable.
> [!WARNING]
>
> YouTube may take up to 24 hours to enable thumbnails after you verify your phone number. Please note, YouTube determines eligibility for adding thumbnails. "Enabled" phone verification does not guarantee YouTube will allow thumbnail uploads.
>
> If you have been verified for 24 hours and still have issues check that:
>
> 1. You are able to manually upload thumbnails in YouTube Studio.
> 2. If you're working with a Brand Content Owner Account (often used for business or organization channels), make sure you have the necessary permissions. We recommend "Owner" rights.
> 3. If you are still having issues, please see this video on [solving the Thumbnail issue](https://www.youtube.com/watch?v=1bFmX2uQk0Y).
## Video: Posting to YouTube via the API
[Posting to YouTube API](https://www.youtube.com/embed/UkisNgVxubg)
## Upload Limits
YouTube limits how many videos a channel can upload in a 24-hour period via the YouTube API.
-
Depending on a creator's location, a channel might be able to increase their daily limit by
getting access to advanced features. To learn more visit this
[article](https://notifications.google.com/g/p/ACnX6LbjUElgT-OfRLVjenkpdldv6pIJ5JYGZyPGTdJwRYmo3fXFkfXJsPGnswgns0BjJ6Bjxn2bqpqfBt6gBdkLoqESKA7mqLNllzcR2qnYUJn5KlJN5jPqCWl6DGr58cZEt94mMvxXATN6_PaBR1RYEpNMTYWN).
-
Limits may vary by country/region or channel history. Copyright strikes may impact channel
history eligibility and [Community Guidelines
strikes](https://support.google.com/youtube/answer/2802032) will affect how much a channel can
upload.
If you receive an upload limit error please wait and try again in 24 hours.
## Description Links
You must activate **Advanced Features** in YouTube Studio to have clickable links in the YouTube video description.
Go to **YouTube Studio -> Settings -> Channel -> Feature Eligibility -> Advanced Features -> Access Features** to activate the advanced features.
## Playlists
You can add videos to a YouTube playlist by including the `playListId` in the `youTubeOptions` object.
Be sure that the authenticated user and channel are the owner of the playlist.
```json YouTube Playlist theme={"system"}
{
"youTubeOptions": {
"playListId": "PLrav6EfwgDX5"
}
}
```
## Subtitles / Captions for Videos
You can add YouTube subtitles, also known as YouTube captions, to videos by including an [SRT file](https://en.wikipedia.org/wiki/SubRip) or a YouTube [SBV file](https://support.google.com/youtube/answer/2734698). Use the `subTitleUrl` field in the `youTubeOptions` object to specify the URL to your SRT or SBV file.
```json YouTube Subtitles theme={"system"}
{
"youTubeOptions": {
"title": "My new post from Ayrshare to Youtube",
"subTitleUrl": "https://img.ayrshare.com/012/captions.srt",
"subTitleLanguage": "en",
"subTitleName": "English"
}
}
```
-
`subTitleUrl`: A valid SRT or SBV file. The URL must start with `https://` and end in `.srt` or
`.sbv` and be a valid SRT or SBV file. The file must be under 100 MB.
-
`subTitleLanguage`: Optional: The language of the subtitles. Must be a valid [language
code](https://www.ayrshare.com/docs/iso-codes/language.md). Default: "en".
-
`subTitleName`: Optional: The name of the caption track. The name is intended to be visible to
the user as an option during playback. The maximum name length supported is 150 characters.
Default: "English".
> [!NOTE]
>
> **What are SRT and SBV files?**
>
> SRT (SubRip Subtitle) and SBV (YouTube SubViewer) are subtitle file formats used for displaying
> timed text in videos. The main difference is that SRT uses timestamps in HH:MM:SS,MS format with
> arrow separators, while SBV uses HH:MM:SS.MS format with commas.
>
> ```text theme={"system"}
> ## SRT Format Example
> 1
> 00:00:01,000 --> 00:00:04,000
> Welcome to our tutorial on subtitle formats.
>
> 2
> 00:00:04,500 --> 00:00:08,000
> Today we'll learn about SRT and SBV files.
>
> ## SBV Format Example
> 0:00:01.000,0:00:04.000
> Welcome to our tutorial on subtitle formats.
>
> 0:00:04.500,0:00:08.000
> Today we'll learn about SRT and SBV files.
> ```
## Tags
You can add YouTube tags to your videos by including the `tags` array in the `youTubeOptions` object.
Tags must be at least 2 characters in length each and the total length of all tags must be 400 characters or less.
```json YouTube Tags theme={"system"}
{
"youTubeOptions": {
"tags": ["dancing", "dogs"]
}
}
```
## YouTube Mentions
While you can add a `@handle` to a YouTube post, YouTube does not support resolving mentions in the post text.
The `@handle` will remain as plain text.
## Character Limits
Please see [YouTube Character Limits](https://www.ayrshare.com/docs/help-center/technical-support/character-limits.md#youtube-character-limits) for more information.
## Unlinking and Revoked Access
If a user removes Ayrshare's access in their Google account, the next YouTube request returns error **250** and Ayrshare unlinks YouTube from that profile. You receive a [social webhook](https://www.ayrshare.com/docs/apis/webhooks/actions.md#social-action) with `"type": "unlink"` and `"source": "system"`, and an email is sent. Relink YouTube to continue posting.
When YouTube is unlinked, whether by you, your user, or automatically, Ayrshare:
* Revokes its access to the Google account, unless the same Google account is still linked to YouTube on another profile, or Ayrshare cannot confirm that it isn't.
* Deletes the YouTube data it stored for that profile 5 days later: YouTube analytics, records of comments sent through Ayrshare, and the YouTube video IDs and URLs in your post history. Your posts stay in your post history without their YouTube links, and the videos stay on YouTube.
YouTube's API policies require this deletion within 7 days. If the same Google account is linked to YouTube on that profile again before then, the data is kept. Relinking after the deletion does not restore it.
## Additional Endpoints
> [card] [Get YouTube Categories](https://www.ayrshare.com/docs/apis/utils/youtube-categories.md)
> [card] [Set YouTube Watermark](https://www.ayrshare.com/docs/apis/utils/set-youtube-watermark.md)
> [card] [Remove YouTube Watermark](https://www.ayrshare.com/docs/apis/utils/remove-youtube-watermark.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.