使用 curl + jq 调用 YouTube Data API v3。用户的 OAuth 持有者令牌位于 $GOOGLE_YOUTUBE_TOKEN 中;每次调用都需要将其作为 Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN 传递。基本 URL:https://www.googleapis.com/youtube/v3。
令牌始终携带 youtube.readonly 以及身份作用域(openid email profile);如果用户在安装时选择加入,它还携带 youtube.upload(发布视频)。
响应是标准 JSON;失败时显示为 {"error": {"code": 401|403|..., "message": "..."}}——请原样显示该错误。401 → 令牌过期,用户必须重新连接 YouTube 连接器。403 insufficientPermissions(上传时)→ 用户未授予 youtube.upload 权限;请要求他们重新连接并勾选上传复选框。
始终从频道检查开始,以确认连接正常并了解你正在操作的频道。
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
"https://www.googleapis.com/youtube/v3/channels?part=snippet,statistics,contentDetails&mine=true" \
| jq '.items[0] | {title: .snippet.title, subs: .statistics.subscriberCount, views: .statistics.viewCount, uploads: .contentDetails.relatedPlaylists.uploads}'
搜索 YouTube
# 公共搜索(任何视频)。type 可以是 video|channel|playlist。
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
--data-urlencode "q=ai video automation" \
--data-urlencode "part=snippet" \
--data-urlencode "type=video" \
--data-urlencode "maxResults=10" \
-G "https://www.googleapis.com/youtube/v3/search" \
| jq '.items[] | {videoId: .id.videoId, title: .snippet.title, channel: .snippet.channelTitle, published: .snippet.publishedAt}'
添加 --data-urlencode "order=date|viewCount|rating|relevance" 进行排序,或添加 --data-urlencode "publishedAfter=2026-01-01T00:00:00Z" 限定时间范围。
查看我上传的视频
YouTube 没有直接的“列出我的视频”调用——需要读取频道的 上传播放列表,然后逐页获取其项目。
# 1. 获取上传播放列表 ID(UU...)——与上面的频道调用相同。
UPLOADS=$(curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
"https://www.googleapis.com/youtube/v3/channels?part=contentDetails&mine=true" \
| jq -r '.items[0].contentDetails.relatedPlaylists.uploads')
# 2. 列出最近上传的视频(每页 50 个;跟踪 .nextPageToken 以获取更多)。
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-G "https://www.googleapis.com/youtube/v3/playlistItems" \
--data-urlencode "part=snippet,contentDetails" \
--data-urlencode "playlistId=$UPLOADS" \
--data-urlencode "maxResults=50" \
| jq '.items[] | {videoId: .contentDetails.videoId, title: .snippet.title, published: .snippet.publishedAt}'
通过将 --data-urlencode "pageToken=$PAGE_TOKEN" 与上次响应中的 .nextPageToken 一起传递来实现分页。
视频统计信息(观看次数/点赞数/评论数)
# 接受逗号分隔的 ID 列表。
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-G "https://www.googleapis.com/youtube/v3/videos" \
--data-urlencode "part=snippet,statistics,status" \
--data-urlencode "id=VIDEO_ID_1,VIDEO_ID_2" \
| jq '.items[] | {title: .snippet.title, views: .statistics.viewCount, likes: .statistics.likeCount, comments: .statistics.commentCount, privacy: .status.privacyStatus}'
读取视频评论
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-G "https://www.googleapis.com/youtube/v3/commentThreads" \
--data-urlencode "part=snippet" \
--data-urlencode "videoId=VIDEO_ID" \
--data-urlencode "maxResults=20" \
--data-urlencode "order=relevance" \
| jq '.items[] | .snippet.topLevelComment.snippet | {author: .authorDisplayName, text: .textDisplay, likes: .likeCount}'
上传视频(需要 youtube.upload)
在发布前与用户确认——显示标题、隐私设置和即将上传的文件。上传是一个两步 可恢复 流程:先用元数据初始化 → 然后 PUT 字节。
FILE="/path/to/video.mp4"
TITLE="My title"
DESC="My description"
# privacyStatus: public | unlisted | private
read -r -d '' META <<JSON
{"snippet":{"title":"$TITLE","description":"$DESC","categoryId":"22"},
"status":{"privacyStatus":"unlisted","selfDeclaredMadeForKids":false}}
JSON
# 1. 初始化可恢复会话 -> 从 Location 标头捕获上传 URL。
UPLOAD_URL=$(curl -sS -D - -o /dev/null \
-H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-H "Content-Type: application/json; charset=UTF-8" \
-H "X-Upload-Content-Type: video/*" \
-X POST "https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=snippet,status" \
-d "$META" | tr -d '\r' | awk '/^[Ll]ocation:/{print $2}')
# 2. 上传字节 -> 返回创建的视频资源(包含 .id)。
curl -sS -H "Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN" \
-H "Content-Type: video/*" \
-X PUT --upload-file "$FILE" "$UPLOAD_URL" \
| jq '{id: .id, url: ("https://www.youtube.com/watch?v=" + .id), privacy: .status.privacyStatus}'
categoryId 22 = "人物与博客"(安全的默认值)。要设置自定义缩略图(需要先处理文件),请调用 POST /upload/youtube/v3/thumbnails/set?videoId=VIDEO_ID 并附带图片。
注意事项
- 配额: Data API 有配额限制(默认每天 10,000 单位)。一次
search消耗 100 单位,一次upload消耗约 1,600 单位。大量搜索可能会耗尽每日配额 → 返回403 quotaExceeded;请直接显示该错误。 - 没有“我的视频”端点——始终通过上传播放列表获取。
search结果是最终一致性的——新上传的视频可能在几分钟或几小时内不会出现在search结果中;请通过上传播放列表或视频 ID 读取。- 上传的视频最初处于
uploaded/processing状态;统计信息在完成处理前为0。