> ## 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

> 使用 YouTube API 發布內容的選項

<Warning>
  發布到 YouTube 需要你的 YouTube 帳號至少擁有一個 Channel，且你必須是該 Channel 的擁有者。
  若要建立 YouTube Channel，請在 YouTube Dashboard 中點擊你的個人資料並選擇「Create a Channel」。
  你也可以透過此直接連結建立 YouTube Channel：[http://m.youtube.com/create\_channel](http://m.youtube.com/create_channel)

  如果你在查看 YouTube channel 時遇到問題，請參閱 [YouTube channel 疑難排解指南](/help-center/technical-support/youtube_channels_not_showing)。
</Warning>

<Info>
  YouTube 上傳失敗可能會回傳錯誤代碼 **453**（逾時）或 **454**
  （服務無法使用），並附上 `retryAvailable: true`。你的整合可以依此旗標
  自動以退避（backoff）重試暫時性失敗。完整清單請參閱
  [錯誤代碼參考](/errors/errors-ayrshare)。
</Info>

更多資訊請參閱 [YouTube 媒體指南](/media-guidelines/youtube) 與 [YouTube 授權](/dashboard/connect-social-accounts/youtube)。

## 發布到 YouTube

### 發布概觀

使用 YouTube API 發布內容時，需要在 `youTubeOptions` 物件中至少提供 `title` 參數 — 最多 100 個字元。
`title` 是唯一的必填欄位，且可透過 [transcribe 端點](/apis/generate/transcribe-video) 自動產生。

例如，使用預設設定發布 YouTube 影片：

```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 影片預設為 `private`，但可將可見性設為 `public` 或 `unlisted`。
可選欄位的詳細說明請參閱下方。

### YouTube 貼文的可選欄位

下方列出了其他多個可選欄位，包含影片的 `visibility`、`tags` 與 `publishAt` 日期。詳細需求與說明請參閱各欄位的註解。

```json YouTube Post Optional Fields theme={"system"}
{
  // Required fields
  "post": "My Best YouTube Description", // Video description, up to 5,000 characters
  "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",
  }
}
```

<ul class="custom-bullets">
  <li>`title` 必須為 100 個字元以下。`post` 必須為 5,000 個字元以下。`post` 與 `title` 可包含任何字元，但不允許 \< 與 >。</li>
  <li>Playlist ID 可透過在瀏覽器中開啟該播放清單、複製 `list=` 後的值取得。已驗證的使用者與 channel 必須是該播放清單的擁有者才能加入影片。</li>
  <li>如果你的影片副檔名不是常見的影片格式（例如 mp4），請使用 `isVideo` 參數。詳情請參閱 [/post 端點](/apis/post/post)。</li>
  <li>`publishAt` 欄位讓 YouTube 控制發布時間。
  在該發布時間之前，影片會維持為 private，到達發布時間後才會轉為公開。
  如果發布時間為過去時間，影片會立即被設為公開。
  使用 `publishAt` 欄位時，不要同時使用貼文的 `scheduleDate` 欄位。</li>
  <li>`containsSyntheticMedia` 欄位用來揭露該影片包含逼真的 Altered 或 Synthetic（A/S）內容：讓真實人物看起來說了或做了他們實際上並沒有說或做的事、竄改真實事件或地點的畫面，或產生實際上並未發生的擬真場景。</li>
  <li>`license` — 設定影片的授權類型。可接受的值：`"youtube"`（Standard YouTube License，預設）或 `"creativeCommon"`（Creative Commons - Attribution）。</li>
  <li>`embeddable` — Boolean（或字串 `"true"` / `"false"`）。控制影片是否可以嵌入到第三方網站。預設：`true`。</li>
  <li>`publicStatsViewable` — Boolean（或字串 `"true"` / `"false"`）。控制影片觀看頁上的**擴充統計面板**是否可公開檢視。基本的觀看次數與按讚數不論此設定為何都會維持公開可見。預設：`true`。詳情請參閱 [YouTube Data API 參考中的 `status.publicStatsViewable`](https://developers.google.com/youtube/v3/docs/videos#status.publicStatsViewable)。</li>
  <li>更多資訊請參閱 [YouTube 媒體指南](/media-guidelines/youtube)。</li>
</ul>

<Note>
  **營利與內容控制**

  `madeForKids`、`license`、`embeddable` 與 `publicStatsViewable` 這些欄位可在上傳時透過 Ayrshare API 設定。然而，直接的營利開關（啟用/停用廣告）、廣告類型選擇（pre-roll、mid-roll、post-roll）、收益分成與 Content ID 都需要 YouTube CMS 憑證 — 這些僅提供給 MCN 與企業內容擁有者 — 因此**無法**透過標準的 YouTube OAuth 或 Ayrshare API 進行設定。
</Note>

## YouTube Shorts

YouTube Short 是一種短影音直式影片，長度最多可達三分鐘。
它類似於 TikTok 影片，以及 Instagram 或 Facebook Reels。

### 發布 YouTube Shorts

在 `youTubeOptions` 物件中加入 `shorts` 參數，即可發布最長 3 分鐘的 YouTube Shorts 影片。

```json YouTube Shorts Post theme={"system"}
{
  "youTubeOptions": {
    "shorts": true
  }
}
```

系統會在 YouTube 描述中加入 <i>#shorts</i> hashtag。

### YouTube Shorts 的重要資訊

<ul class="custom-bullets">
  <li>
    將影片以 Short 發送只是向 YouTube 表明你希望該影片以 Short 呈現，但並不保證
    一定會以 Short 呈現。該影片必須符合 [Short
    影片](/media-guidelines/youtube#shorts)的需求（例如 3 分鐘以內、9:16 直式比例），
    YouTube 才會將其視為 Short。
  </li>

  <li>YouTube Shorts 不支援縮圖。</li>

  <li>
    更多關於使用 [API 發布 YouTube
    Shorts](https://www.ayrshare.com/blog/post-youtube-shorts-with-an-api/) 的資訊。
  </li>
</ul>

## YouTube 縮圖

<Info>
  自訂縮圖需要**已驗證的 YouTube channel**。縮圖套用失敗（但影片仍成功發布）最常見的原因就是 channel 未經驗證 — 請至 [https://www.youtube.com/verify](https://www.youtube.com/verify)（電話驗證）進行驗證。你的 `thumbNail` 也必須是 **PNG 或 JPG/JPEG** 格式、**2MB 以下**，並來自**可存取的 URL**；Ayrshare 會在可能的情況下於發布前驗證這些條件。當影片發布成功但縮圖套用失敗時，YouTube 結果仍會維持 `status: "success"`，並加上一個 `warnings` 陣列（`feature: "thumbnail"`、`code: 307`）描述失敗原因。完整解法請參閱 [YouTube 縮圖未套用（Channel 未驗證）](/help-center/technical-support/youtube_thumbnail_unverified_channel)。
</Info>

### 加入 YouTube 縮圖

YouTube 縮圖以及其他功能（例如上傳 15 分鐘影片），都需要驗證你的電話號碼。
`thumbNail` 是 JPEG 或 PNG 檔案的 URL，且大小需小於 2MB。副檔名必須為 png、jpg 或 jpeg。

```json YouTube Thumbnail theme={"system"}
{
  "youTubeOptions": {
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg"
  }
}
```

YouTube Shorts 目前尚未支援縮圖。

### 在 YouTube Studio 中啟用縮圖

你必須取得 YouTube 權限才能發布縮圖。在 [YouTube Studio](https://studio.youtube.com/) 中前往 *Settings->Channel*。選擇「*Feature Eligibility*」並點擊「*Features that require phone verification*」，輸入你的電話號碼即可啟用。

<img class="center" src="https://mintcdn.com/ayrshare-docs/Nmrhj2Gh7WSf62Bh/images/apis/post/yt-thumb.webp?fit=max&auto=format&n=Nmrhj2Gh7WSf62Bh&q=85&s=67855a44b4ab5612d5f89df9db511556" alt="YouTube Studio" width="1200" height="781" data-path="images/apis/post/yt-thumb.webp" />

<Warning>
  YouTube 在你完成電話驗證後，最多可能需要 24 小時才會啟用縮圖功能。請注意，是否可以新增縮圖由 YouTube 決定。「已啟用」電話驗證並不保證 YouTube 會允許縮圖上傳。

  如果驗證超過 24 小時仍有問題，請確認：

  1. 你是否能在 YouTube Studio 中手動上傳縮圖。
  2. 如果你使用的是 Brand Content Owner Account（通常用於公司或組織 channel），請確認你擁有必要的權限。我們建議取得「Owner」權限。
  3. 如果仍有問題，請參閱這支影片 [解決縮圖問題](https://www.youtube.com/watch?v=1bFmX2uQk0Y)。
</Warning>

## 影片：透過 API 發布到 YouTube

<iframe width="380" height="200" src="https://www.youtube.com/embed/UkisNgVxubg" title="Posting to YouTube API" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" />

## 上傳限制

YouTube 透過 YouTube API 限制每個 channel 在 24 小時內能上傳的影片數量。

<ul class="custom-bullets">
  <li>
    依創作者的所在地不同，channel 可能可以透過取得進階功能來提高每日的上限。
    詳情請參閱這篇
    [文章](https://notifications.google.com/g/p/ACnX6LbjUElgT-OfRLVjenkpdldv6pIJ5JYGZyPGTdJwRYmo3fXFkfXJsPGnswgns0BjJ6Bjxn2bqpqfBt6gBdkLoqESKA7mqLNllzcR2qnYUJn5KlJN5jPqCWl6DGr58cZEt94mMvxXATN6_PaBR1RYEpNMTYWN)。
  </li>

  <li>
    上限可能會因國家/地區或 channel 歷史而有所不同。著作權違規可能會影響
    channel 歷史的資格，而 [社群規範
    違規](https://support.google.com/youtube/answer/2802032) 則會影響
    channel 可上傳的數量。
  </li>
</ul>

如果你收到上傳限制錯誤，請等待並在 24 小時後再試一次。

## 描述連結

你必須在 YouTube Studio 中啟用 **Advanced Features**，YouTube 影片描述中的連結才能點擊。

前往 **YouTube Studio -> Settings -> Channel -> Feature Eligibility -> Advanced Features -> Access Features** 來啟用進階功能。

<img class="center" src="https://mintcdn.com/ayrshare-docs/Nmrhj2Gh7WSf62Bh/images/apis/post/YT-settings.webp?fit=max&auto=format&n=Nmrhj2Gh7WSf62Bh&q=85&s=129f12886c2896167f936dcc7c633234" alt="YouTube Feature Eligibility" width="1000" height="661" data-path="images/apis/post/YT-settings.webp" />

## 播放清單

透過在 `youTubeOptions` 物件中加入 `playListId`，可以將影片加入 YouTube 播放清單。
請確認已驗證的使用者與 channel 是該播放清單的擁有者。

```json YouTube Playlist theme={"system"}
{
  "youTubeOptions": {
    "playListId": "PLrav6EfwgDX5"
  }
}
```

## 影片字幕

你可以透過在 `youTubeOptions` 物件中提供 [SRT 檔案](https://en.wikipedia.org/wiki/SubRip) 或 YouTube [SBV 檔案](https://support.google.com/youtube/answer/2734698) 為影片加上 YouTube 字幕（YouTube captions）。使用 `subTitleUrl` 欄位指定你的 SRT 或 SBV 檔案的 URL。

```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"
  }
}
```

<ul class="custom-bullets">
  <li>
    `subTitleUrl`：有效的 SRT 或 SBV 檔案。URL 必須以 `https://` 開頭並以 `.srt` 或
    `.sbv` 結尾，且為有效的 SRT 或 SBV 檔案。檔案大小必須小於 100 MB。
  </li>

  <li>
    `subTitleLanguage`：選填：字幕的語言。必須是有效的 [語言
    代碼](/iso-codes/language)。預設："en"。
  </li>

  <li>
    `subTitleName`：選填：字幕軌道的名稱。此名稱在播放時會顯示給
    使用者作為選項。最多可支援 150 個字元。
    預設："English"。
  </li>
</ul>

<Note>
  **什麼是 SRT 與 SBV 檔案？**

  SRT（SubRip Subtitle）與 SBV（YouTube SubViewer）是字幕檔案格式，用於在影片中顯示
  帶有時間軸的文字。兩者主要差異在於 SRT 使用 HH:MM:SS,MS 格式的時間戳並以箭頭分隔，
  而 SBV 則使用 HH:MM:SS.MS 格式並以逗號分隔。

  ```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.
  ```
</Note>

## Tags

透過在 `youTubeOptions` 物件中加入 `tags` 陣列，即可為影片加上 YouTube 標籤。
每個標籤至少須有 2 個字元，且所有標籤合計長度須為 500 個字元以下。

```json YouTube Tags theme={"system"}
{
  "youTubeOptions": {
    "tags": ["dancing", "dogs"]
  }
}
```

## YouTube 提及

雖然你可以在 YouTube 貼文中加入 `@handle`，但 YouTube 不會解析貼文文字中的提及。
`@handle` 將保持為純文字顯示。

## 字元限制

更多資訊請參閱 [YouTube 字元限制](/help-center/technical-support/character_limits#youtube-character-limits)。

## 其他端點

<Card title="取得 YouTube 分類" icon="code" href="/apis/utils/youtube-categories" horizontal />

<Card title="設定 YouTube 浮水印" icon="code" href="/apis/utils/set-youtube-watermark" horizontal />

<Card title="移除 YouTube 浮水印" icon="code" href="/apis/utils/remove-youtube-watermark" horizontal />