Back to Details

youtube

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Call the YouTube Data API v3 with 
curl + jq
. The user's OAuth bearer token is in 
$GOOGLE_YOUTUBE_TOKEN
; every call needs it as 
Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN
. Base URL: 
https://www.googleapis.com/youtube/v3
.
The token always carries 
youtube.readonly
plus identity scopes (
openid email profile
); if the user opted in at install it also carries 
youtube.upload
(publish videos).
Responses are standard JSON; failures surface as 
{"error": {"code": 401|403|..., "message": "..."}}
— show that error verbatim. 
401
→ token expired, the user must re-connect the YouTube connector. 
403 insufficientPermissions
on an upload → the user did not grant 
youtube.upload
; ask them to re-connect with the upload box checked.
Always start with the channel check to confirm the connection works and learn which channel you're operating against.
bash
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}'
使用
curl + jq
调用YouTube Data API v3。用户的OAuth bearer token存储在
$GOOGLE_YOUTUBE_TOKEN
中；每次调用都需要将其作为
Authorization: Bearer $GOOGLE_YOUTUBE_TOKEN
携带。基础URL：
https://www.googleapis.com/youtube/v3
。
该token默认包含
youtube.readonly
权限及身份范围（
openid email profile
）；如果用户在安装时选择了相关选项，还会包含
youtube.upload
权限（用于发布视频）。
返回结果为标准JSON格式；失败时会返回
{"error": {"code": 401|403|..., "message": "..."}}
— 需直接展示该错误信息。
401
错误表示token已过期，用户必须重新连接YouTube连接器。上传时出现
403 insufficientPermissions
错误，表示用户未授予
youtube.upload
权限；请提示用户重新连接并勾选上传权限选项。
请始终先执行频道检查，确认连接正常并明确当前操作的频道。
bash
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}'

Search YouTube

搜索YouTube

bash
undefined
bash
undefined

Public search (any video). type can be video|channel|playlist.

公开搜索（所有视频）。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}'

Add `--data-urlencode "order=date|viewCount|rating|relevance"` to sort,
or `--data-urlencode "publishedAfter=2026-01-01T00:00:00Z"` to window.
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"`限定时间范围。

See my uploaded videos

查看我上传的视频

YouTube has no "list my videos" call directly — read the channel's uploads playlist, then page its items.
bash
undefined
YouTube没有直接“列出我的视频”的接口 — 需先读取频道的上传播放列表，再分页获取其中的内容。
bash
undefined

1. Get the uploads playlist id (UU... ) — same as channels call above.

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')
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. List recent uploads (50/page; follow .nextPageToken for more).

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}'

Paginate by passing `--data-urlencode "pageToken=$PAGE_TOKEN"` with the
`.nextPageToken` from the previous response.
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}'

分页时，需将上一次返回结果中的`.nextPageToken`作为`--data-urlencode "pageToken=$PAGE_TOKEN"`参数传入。

Video stats (views / likes / comments)

视频数据统计（播放量/点赞数/评论数）

bash
undefined
bash
undefined

Accepts a comma-separated id list.

支持传入逗号分隔的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}'
undefined
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}'
undefined

Read comments on a video

查看视频评论

bash
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}'
bash
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}'

Upload a video (needs 
youtube.upload
)

上传视频（需要
youtube.upload
权限）

Confirm with the user before publishing — show the title, privacy and file you're about to upload. Uploads are a two-step resumable flow: init with metadata → PUT the bytes.
bash
FILE="/path/to/video.mp4"
TITLE="My title"
DESC="My description"
发布前请与用户确认 — 展示即将上传的视频标题、隐私设置及文件路径。上传分为两步可恢复流程：先初始化元数据 → 再上传文件字节。
bash
FILE="/path/to/video.mp4"
TITLE="My title"
DESC="My description"

privacyStatus: public | unlisted | private

privacyStatus可选值：public | unlisted | private

read -r -d '' META <<JSON {"snippet":{"title":"$TITLE","description":"$DESC","categoryId":"22"}, "status":{"privacyStatus":"unlisted","selfDeclaredMadeForKids":false}} JSON
read -r -d '' META <<JSON {"snippet":{"title":"$TITLE","description":"$DESC","categoryId":"22"}, "status":{"privacyStatus":"unlisted","selfDeclaredMadeForKids":false}} JSON

1. Init resumable session -> capture the upload URL from the Location header.

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}')
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. Upload the bytes -> returns the created video resource (has .id).

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` = "People & Blogs" (a safe default). To set a custom
thumbnail (needs the file to be processed first), call
`POST /upload/youtube/v3/thumbnails/set?videoId=VIDEO_ID` with the image.
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`接口并上传图片即可。

Gotchas

注意事项

  • Quota: the Data API is quota-metered (default 10,000 units/day). A 
    search
    costs 100 units; an 
    upload
    costs ~1,600. A burst of searches can exhaust the daily quota → 
    403 quotaExceeded
    ; surface it plainly.
  • No "my videos" endpoint — always go via the uploads playlist.
  • search
    results are eventually-consistent     — a freshly uploaded video may not appear in 
    search
    for minutes/hours; read it via the uploads playlist or by id instead.
  • Uploaded videos start in 
    uploaded
    /
    processing
    state; stats are 
    0
    until processing completes.
  • 配额限制：Data API采用配额计量制（默认每日10000单位）。一次
    search
    请求消耗100单位；一次
    upload
    请求消耗约1600单位。短时间内多次搜索可能耗尽每日配额，触发
    403 quotaExceeded
    错误；需直接向用户展示该错误信息。
  • 无“我的视频”端点 — 必须通过上传播放列表获取个人视频。
  • search
    结果最终一致性     — 刚上传的视频可能需要数分钟甚至数小时才会出现在搜索结果中；可通过上传播放列表或视频ID直接查看。
  • 上传的视频初始状态为
    uploaded
    /
    processing
    ；在处理完成前，数据统计值为
    0
    。