YouTube 頻道分析
scripts/channel_profile.py 透過 YouTube Data API v3 讀取公開頻道資料，並產出 Markdown 報告，或使用 --json 輸出 JSON。它只使用官方 API，從不載入 YouTube 網頁，也不會寫入任何資料到磁碟。
執行前準備
- 使用者需要一個 Google Cloud 專案，已啟用 YouTube Data API v3 並取得一個僅限該 API 使用的 API 金鑰。
- 金鑰需設定在
YOUTUBE_API_KEY環境變數中。切勿將其放入提示詞、檔案、對話中，也絕不能列印出來。如果該變數未設定，請停止並要求使用者設定。請勿在其他地方尋找金鑰。 - 安裝一個依賴套件：
pip install -r scripts/requirements.txt（即 requests）。
執行
python3 scripts/channel_profile.py @handle
python3 scripts/channel_profile.py https://www.youtube.com/@handle --videos 100
python3 scripts/channel_profile.py UCxxxxxxxxxxxxxxxxxxxxxx --json
選項：--videos N（要讀取的近期上傳數量，預設 50，最多 500）、--json、--no-search、--cpm-low 和 --cpm-high（預設值為 0.25 和 4.00）。
頻道搜尋方式
- 頻道 ID 或
/channel/UC...網址：使用channels.list搭配id。 @handle或/@handle網址：使用channels.list搭配forHandle。/user/網址：使用forUsername。/c/網址會嘗試作為 handle。- 如果以上皆不符合，則會退回使用
search.list尋找最佳匹配，並在報告中說明。請在依賴結果前檢查標題和 ID。--no-search可關閉此備用機制。 - 影片連結、播放清單連結及非 YouTube 網址會被拒絕。請要求提供頻道連結。
配額
| 呼叫 | 費用 |
|---|---|
channels.list | 1 單位 |
playlistItems.list | 每 50 部上傳 1 單位 |
videos.list | 每 50 部影片 1 單位 |
search.list（僅備用） | 1 次呼叫（使用獨立配額） |
預設執行會耗用每日 10,000 單位預設配額中的 3 單位。自 2026 年 6 月 1 日起，search.list 擁有每日 100 次呼叫的獨立配額。在此之前，一次搜尋會從主要配額中耗用 100 單位，因此舊版指南會顯示 100。失敗的呼叫仍會消耗配額。配額於太平洋時間午夜重置。每份報告結尾會顯示所耗用的配額。
報告內容
來自 YouTube 的原始資料：
- 訂閱數，YouTube 會將其四捨五入至三位有效數字。如果擁有者隱藏了該數字，報告會顯示「隱藏」且不提供猜測。
- 頻道總觀看次數與公開影片數量。
- 每部近期影片的觀看次數、喜歡數與留言數。
由腳本計算並以 * 標記的衍生資料：
- 上片節奏：最近 N 部上傳之間的中位數天數、每月上傳數（(N - 1) 個間隔 / 總天數 x 30.44）以及距離上次上傳的天數。
- 近期影片的中位數與平均觀看次數。直播與即將上線的影片會被排除。
- 趨勢：最後 10 部上傳與前 10 部上傳的中位數觀看次數比較。較新的影片累積觀看次數的時間較短。
- 互動率：每部影片的（喜歡數 + 留言數）/ 觀看次數，再取中位數。隱藏喜歡數的影片會被排除。關閉留言功能的影片，留言數計為 0。
- 依時長區分 Shorts 與長片。這是一種啟發式方法：時長 180 秒或以下視為 Shorts，因為 API 沒有專門的 Shorts 標記。
- 按觀看次數排序的前 5 名熱門影片。
- 預估每月觀看次數：過去 30 天內發布的影片當前觀看次數總和。這不包括舊片庫的觀看次數。如果樣本未涵蓋過去 30 天，報告會說明並建議增大
--videos參數。該檢查假設上傳播放清單按最新優先排列（通常如此）。
YouTube API 政策 III.E.4.h 允許在 YouTube 自己的總數旁邊顯示衍生數據，但需明確註明這些數據並非來自 YouTube。報告已遵循此規範。每當引用標有星號的數據時，請務必附上該註明。
收益計算方式
低估值 = 預估每月觀看次數 / 1,000 x US$0.25
高估值 = 預估每月觀看次數 / 1,000 x US$4.00
US$0.25 到 US$4.00 是 Social Blade 公布的預設 CPM 區間（socialblade.com/youtube/calculator）。報告會以實際數字展示此公式。這僅是廣告收入，不包括贊助、會員、購物、聯盟行銷以及粉絲資助。實際 RPM 會因利基、觀眾國家與影片格式而異。Shorts 收入以不同條款合併計算。未加入 YouTube 合作夥伴計畫的頻道不會獲得任何廣告收入。請務必稱其為「預估區間」，而非實際收入。
錯誤代碼
| 退出碼 | 意義 | 處理方式 |
|---|---|---|
| 0 | 報告已產出 | |
| 2 | 輸入錯誤、缺少金鑰或找不到頻道 | 修正輸入，或要求使用者提供金鑰或正確連結 |
| 3 | 配額用盡 | 停止。告知使用者配額將於太平洋時間午夜重置。請勿在迴圈中重試或切換金鑰 |
| 4 | 其他 API 錯誤，例如金鑰無效或 API 未啟用 | 向使用者顯示錯誤訊息 |
| 5 | 網路錯誤 | 重試一次，若仍失敗則回報 |
錯誤訊息會輸出失敗前已耗用的配額。所有訊息與報告在輸出前都會清除金鑰。
規則
- 僅使用官方 API。切勿為了填補資料缺口而爬取 YouTube 網頁。應報告該缺口。
- 不緩存任何超出此次執行的資料。不儲存原始 API 回應。如果使用者保留報告，API 統計資料不得儲存超過 30 天（政策 III.E.4.b）。
- 僅處理公開資料。觀眾人口統計非公開資訊：請參閱
creator-audience技能。
最後檢查日期：2026 年 11 月 5 日，對照 YouTube Data API 參考文件、配額頁面、修訂歷史與開發者政策。腳本的測試在離線模式下使用固定資料進行。此處尚未對正式 API 執行。