PAYATHON 2026

PHP 调用 YouTube Data API thumbnails->set() 设置视频缩略图

数据小陈

结论

$content 不能放进 thumbnails->set() 的 $optParams。这个参数只用来放查询参数,比如 onBehalfOfContentOwner 等;缩略图的二进制内容属于上传媒体,得另外处理。PHP 客户端的做法是先用 $client->setDefer(true),让 thumbnails->set($videoId) 返回一个还没执行的请求,再用 Google_Http_MediaFileUpload(新版本可能是 Google\Http\MediaFileUpload)把这个请求包装起来,通过 nextChunk() 上传图片。

示例代码

<?php
$FILENAME = "/www/files/ytThumbs/image91.png" ;
$ytId = 'abcdefghijk' ;

$ytService = $yt->GetYouTubeService() ;
$client = $ytService->getClient() ; // 如果 GetYouTubeService() 返回 Google\Service\YouTube

$client->setDefer(true) ;

// 1. 生成尚未执行的 thumbnails.set 请求
$setRequest = $ytService->thumbnails->set($ytId) ;

// 2. 包装为媒体上传请求
$chunkSizeBytes = 1 * 1024 * 1024 ;
$media = new Google_Http_MediaFileUpload(
    $client,
    $setRequest,
    'image/png', // 若文件是 .jpg 则改为 image/jpeg
    null,
    true,
    $chunkSizeBytes
) ;
$media->setFileSize(filesize($FILENAME)) ;

$status = false ;
$handle = fopen($FILENAME, 'rb') ;
while (!$status && !feof($handle)) {
    $chunk = fread($handle, $chunkSizeBytes) ;
    $status = $media->nextChunk($chunk) ;
}
fclose($handle) ;

$client->setDefer(false) ;

if ($status) {
    // $status 是 Google\Service\YouTube\ThumbnailSetResponse
    var_dump($status) ;
} else {
    echo "thumbnail upload failed\n" ;
}

关键说明

  • 一定要用 setDefer(true),否则 thumbnails->set() 可能马上发出一个不带媒体内容的请求。
  • 图片的 MIME 类型要和文件对得上:PNG 用 image/png,JPEG 用 image/jpeg。
  • 这个接口要求当前 OAuth 客户端有管理该视频的权限,登录账号也得是视频所有者,或者是有权限的频道账号。常用的 scope 有 https://www.googleapis.com/auth/youtube.upload 和 https://www.googleapis.com/auth/youtube,具体以官方文档和控制台配置为准。
  • 缩略图文件要符合 YouTube 的限制,比如大小不超过 2 MB,建议用 1280x720、16
    的图片。
  • 如果用的是新命名空间,就把 Google_Http_MediaFileUpload 换成 Google\Http\MediaFileUpload,并按项目的自动加载方式引入。
  • 已经用 file_get_contents() 把图片读进 $content 的话,简单上传可以直接把 $content 当作 MediaFileUpload 的 $data 参数传进去;不过分块上传的示例一般传 null,再从文件流里读 chunk,免得一次性占用太多内存。

备注:内容仅供参考。