YouTube 發佈

了解如何連結 YouTube 頻道，並上傳包含中繼資料與自訂縮圖的影片。

連結 YouTube 頻道

前置需求

擁有 YouTube 頻道
具備該頻道存取權的 Google 帳號
已登入 Boring 控制台

連結步驟

在控制台按下 「Connect YouTube」
如未登入 Google，請先登入
選擇要連結的 YouTube 頻道
檢視並授予必要權限：
- youtube.upload：上傳影片
- youtube：管理頻道
- youtube.readonly：讀取頻道資訊
點擊 「Allow」 完成授權

完成後，頻道會出現在「Authorized Accounts」列表，顯示：

頻道名稱
頻道縮圖
平台標籤（YouTube）
唯一帳號 ID（可透過「Copy ID」複製）
解除連結選項

權杖資訊

權杖類型：OAuth 2.0 Access Token + Refresh Token
存取權杖有效期：1 小時
自動刷新：使用 Refresh Token 自動取得新權杖
重新授權：僅在 Refresh Token 被撤銷時需要

支援的內容類型

YouTube 支援附帶豐富中繼資料的影片上傳：

功能	說明	是否必填	限制
影片	影片檔案 URL	是	MP4、MOV、AVI…
標題	影片標題	是	最多 100 字元
描述	影片描述	否	最多 5,000 字元
標籤	關鍵字	否	最多 500 個
縮圖	自訂縮圖	否	JPG、PNG（建議 1280x720）
隱私	公開權限	否	預設為 public

發佈範例

1. 基本影片（只有標題）

{
  "post": {
    "accountId": "your-youtube-channel-account-id",
    "content": {
      "text": "My Awesome Video Title",
      "mediaUrls": ["https://example.com/video.mp4"],
      "platform": "youtube"
    },
    "target": {
      "targetType": "youtube"
    }
  }
}

效果：僅設定標題的影片上傳。

2. 影片 + 標題與描述

text 欄位使用 \n\n（兩個換行）來分隔標題與描述：

{
  "post": {
    "accountId": "your-youtube-channel-account-id",
    "content": {
      "text": "Complete Guide to API Integration\n\nIn this comprehensive tutorial, we'll walk through the entire process of integrating our API into your application. Perfect for beginners and advanced developers alike!\n\n#API #Tutorial #Programming",
      "mediaUrls": ["https://example.com/tutorial-video.mp4"],
      "platform": "youtube"
    },
    "target": {
      "targetType": "youtube"
    }
  }
}

文字格式：

\n\n 前：影片標題（最多 100 字元）
\n\n 後：影片描述（最多 5,000 字元）
描述中出現的 #標籤 會變成影片標籤

效果：

標題：Complete Guide to API Integration
描述：In this comprehensive tutorial…
標籤：["API", "Tutorial", "Programming"]

3. 影片 + 自訂縮圖

mediaUrls 第二個元素可提供縮圖：

{
  "post": {
    "accountId": "your-youtube-channel-account-id",
    "content": {
      "text": "Product Launch Event 2025\n\nJoin us for the biggest product launch of the year! See all the new features and innovations we've been working on. Don't miss out! #ProductLaunch #Tech #Innovation",
      "mediaUrls": [
        "https://storage.example.com/launch-video.mp4",
        "https://storage.example.com/thumbnail.jpg"
      ],
      "platform": "youtube"
    },
    "target": {
      "targetType": "youtube"
    }
  }
}

mediaUrls 陣列：

mediaUrls[0]：影片檔案 URL（必填）
mediaUrls[1]：縮圖 URL（選填）

API 請求範例

Python 範例

import requests

API_URL = "https://boring.aiagent-me.com/v2/posts"
API_KEY = "boring_xxxxxxxxxxxxx"
ACCOUNT_ID = "your-youtube-channel-account-id"

post_data = {
    "post": {
        "accountId": ACCOUNT_ID,
        "content": {
            "text": "Product Demo 2025\n\nFull walkthrough of the new features. #ProductDemo #SaaS",
            "mediaUrls": [
                "https://storage.example.com/demo-video.mp4",
                "https://storage.example.com/demo-thumbnail.jpg"
            ],
            "platform": "youtube"
        },
        "target": {
            "targetType": "youtube"
        }
    }
}

headers = {
    "boring-api-key": API_KEY,
    "Content-Type": "application/json"
}

response = requests.post(API_URL, headers=headers, json=post_data)
result = response.json()

if result.get("success"):
    print("Video uploaded successfully!")
    print(f"Video ID: {result['video_id']}")
    print(f"Watch at: {result['video_url']}")
    print(f"Thumbnail uploaded: {result.get('thumbnail_uploaded', False)}")
else:
    print(f"Upload failed: {result.get('error')}")

成功回應

{
  "success": true,
  "message": "Post published successfully",
  "postSubmissionId": "uuid-here",
  "platform": "youtube",
  "post_type": "video",
  "video_id": "dQw4w9WgXcQ",
  "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "thumbnail_uploaded": true
}

文字格式指南

使用 `\n\n` 分隔

text 欄位中的 \n\n 用於分隔標題與描述。

❌ 錯誤：只有單個換行 \n

{
  "text": "My Title\nMy Description"
}

效果：整段文字皆視為標題，描述為空。

✅ 正確：使用雙換行 \n\n

{
  "text": "My Title\n\nMy Description"
}

效果：

標題：My Title
描述：My Description

各語言示例

Python

text = "Video Title\n\nThis is the description with #hashtags"

# 或使用三引號讓內容可讀性更高
text = """Video Title

This is the description with #hashtags"""

JavaScript

const text = "Video Title\n\nThis is the description with #hashtags";

// 或使用模板字面值
const text = `Video Title

This is the description with #hashtags`;

cURL

curl -X POST https://boring.aiagent-me.com/v2/posts \
  -H "boring-api-key: boring_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "post": {
      "accountId": "your-account-id",
      "content": {
        "text": "Video Title\n\nVideo description here",
        "mediaUrls": ["https://example.com/video.mp4"],
        "platform": "youtube"
      },
      "target": {"targetType": "youtube"}
    }
  }'

影片需求

支援格式

容器：MP4、MOV、AVI、WMV、FLV、3GPP、WebM、MPEG-PS
編碼：H.264、H.265、VP9、AV1
音訊：AAC、MP3、Vorbis、Opus

檔案規格

檔案大小：官方無硬性限制（實測可達 256GB）
影片長度：最多 12 小時（未驗證帳號限制 15 分鐘）
建議解析度：1080p（1920x1080）以上
建議位元率：1080p 8 Mbps、4K 16 Mbps
長寬比：16:9（建議）、4:3、9:16（Shorts）

上傳流程

下載：從提供的 URL 下載影片
上傳：使用可續傳上傳（resumable upload）
處理：YouTube 進行轉碼與處理
縮圖：若提供縮圖則上傳
發佈：依隱私設定公開

伺服器日誌範例：

[YOUTUBE] Upload progress: 33%
[YOUTUBE] Upload progress: 67%
[YOUTUBE] Upload progress: 100%
[YOUTUBE] Video uploaded successfully! Video ID: abc123
[YOUTUBE] Thumbnail uploaded successfully

隱私設定

目前影片預設為 public。未來版本規劃支援：

public：任何人可觀看
unlisted：持有連結者可觀看
private：僅限自己觀看
scheduled：排程於特定時間發布

疑難排解

常見錯誤

錯誤：「Video URL is required」

原因：mediaUrls 未提供影片 URL
解法：將影片 URL 放在第一個元素，例如 "mediaUrls": ["video.mp4"]

錯誤：「Failed to download video」

原因：影片 URL 無法存取
解法：
- 確認 URL 可公開下載
- 使用 curl -I https://your-video-url.mp4 測試
- 確保不需額外驗證

錯誤：「YouTube service not initialized」

原因：OAuth 權杖問題
解法：重新連結 YouTube 頻道

錯誤：「Thumbnail upload failed」

原因：縮圖不符合規格或權限不足
說明：影片仍成功上傳，只有縮圖失敗
解法：
- 確認縮圖符合 1280x720、JPG/PNG
- 確認縮圖 URL 可公開存取
- 可稍後在 YouTube Studio 中重新上傳縮圖

上傳時間過久？

上傳時間取決於：

影片大小：檔案越大耗時越久
上傳來源：你的雲端儲存連線速度
YouTube 處理時間：轉碼需額外時間

參考時間：

100MB 影片：30-60 秒
500MB 影片：2-5 分鐘
1GB 影片：5-10 分鐘

最佳實務

先用小型影片測試：確認流程無誤
使用穩定雲端託管：建議 GCS、S3…等
優化影片檔案：使用 H.264 編碼並適度壓縮
設計吸睛縮圖：1280x720、亮眼配色、清晰文字
撰寫 SEO 友善描述：置入關鍵字
善用 Hashtag：描述中加入 3-5 個相關標籤
監控上傳狀態：在控制台查看錯誤訊息

發佈歷史

在控制台檢視所有 YouTube 上傳紀錄：

登入 Boring 控制台
捲動至 「Recent Posts」 區塊
篩選平台為 YouTube

每筆紀錄顯示：

影片標題
影片 ID 與 YouTube 連結
上傳狀態（成功/失敗）
縮圖狀態
時間戳記
若失敗則顯示錯誤訊息

速率限制

YouTube API 配額規則：

預設配額：每日 10,000 單位
影片上傳：每次消耗 1,600 單位
縮圖上傳：每次消耗 50 單位

每日可容量：預設配額約可上傳 6 支影片

若需更高配額，可於 Google Cloud Console 申請。

Boring 會妥善處理配額不足的錯誤並回傳對應訊息。

進階功能

多個頻道

同一個 Boring 帳號可連結多個 YouTube 頻道，每個頻道都有獨立帳號 ID。

操作流程：

連結頻道 A，取得帳號 ID：aaa-111
連結頻道 B，取得帳號 ID：bbb-222
使用 accountId: "aaa-111" 上傳至頻道 A
使用 accountId: "bbb-222" 上傳至頻道 B

批次上傳

透過程式批次上傳多支影片：

videos = [
    {
        "title": "Episode 1: Introduction",
        "description": "Welcome to our series!",
        "video_url": "https://example.com/ep1.mp4",
        "thumbnail_url": "https://example.com/ep1-thumb.jpg"
    },
    {
        "title": "Episode 2: Getting Started",
        "description": "Let's dive deeper!",
        "video_url": "https://example.com/ep2.mp4",
        "thumbnail_url": "https://example.com/ep2-thumb.jpg"
    }
]

for video in videos:
    post_data = {
        "post": {
            "accountId": ACCOUNT_ID,
            "content": {
                "text": f"{video['title']}\n\n{video['description']}",
                "mediaUrls": [video['video_url'], video['thumbnail_url']],
                "platform": "youtube"
            },
            "target": {"targetType": "youtube"}
        }
    }

    response = requests.post(API_URL, headers=headers, json=post_data)
    print(f"Uploaded: {video['title']} - {response.json()}")

    # 間隔上傳避免配額限制
    time.sleep(60)

速查表

最精簡上傳（標題 + 影片）

{
  "post": {
    "accountId": "your-account-id",
    "content": {
      "text": "Video Title",
      "mediaUrls": ["https://example.com/video.mp4"],
      "platform": "youtube"
    },
    "target": {"targetType": "youtube"}
  }
}

完整上傳（標題 + 描述 + 縮圖）

{
  "post": {
    "accountId": "your-account-id",
    "content": {
      "text": "Video Title\n\nDetailed description with #tags",
      "mediaUrls": [
        "https://example.com/video.mp4",
        "https://example.com/thumbnail.jpg"
      ],
      "platform": "youtube"
    },
    "target": {"targetType": "youtube"}
  }
}

下一步

Facebook 發佈：深入了解 Facebook
Instagram 發佈：掌握 Instagram 流程
Threads 發佈：發揮 Threads 串文優勢
API 參考：完整 API 文件
程式範例：查看更多範例