The PHP client’s thumbnails->set() method takes the video ID first and media-upload options second. Put the image bytes in data, specify its MIME type, and set uploadType to media. The authenticated channel must own the video and be allowed to use custom thumbnails.
Last updated: October 7, 2026.
<?php
use GoogleClient;
use GoogleServiceYouTube;
require __DIR__ . '/vendor/autoload.php';
$imagePath = __DIR__ . '/thumbnail.jpg';
$mime = (new finfo(FILEINFO_MIME_TYPE))->file($imagePath);
if (!in_array($mime, ['image/jpeg', 'image/png'], true)) {
throw new RuntimeException('Thumbnail must be JPEG or PNG.');
}
$client = new Client();
$client->setAccessToken(json_decode(
file_get_contents(__DIR__ . '/secrets/token.json'),
true
));
$youtube = new YouTube($client);
$response = $youtube->thumbnails->set('YOUR_VIDEO_ID', [
'data' => file_get_contents($imagePath),
'mimeType' => $mime,
'uploadType' => 'media',
]);
printf("Uploaded %d thumbnail(s).
", count($response->getItems()));Install the client with composer require google/apiclient. The example assumes a valid OAuth access token already exists. Store tokens outside the public web directory and refresh expired access tokens securely.
The image belongs in media options
The generated resource method exposes the API’s query parameters in its signature, while the shared PHP client adds media options such as data, mimeType, and uploadType. The request body is the image itself; it is not a thumbnail metadata resource.
Google’s thumbnails.set reference lists accepted media types, the 50 MB limit, authorization scopes, quota cost, and common errors. The client library’s media upload guide documents the PHP options used above.
Handle authorization and API errors explicitly
An API key is not enough because this call modifies a channel. Use OAuth consent for the channel owner and request a documented scope. A 403 can mean the account does not own the video, lacks custom-thumbnail permission, or authorized the wrong channel. A 400 “mediaBodyRequired” response means the image bytes were omitted.
Validate local files and size before sending them, and never log tokens. Continue with validating JPEG uploads, creating thumbnails with PHP, and building a secure upload pipeline.
