Thumbnails: set

YouTube에 맞춤 동영상 미리보기 이미지를 업로드하고 이를 동영상에 설정합니다. 예를 참조하세요.

이 메소드는 업로드한 미디어를 지원합니다. 업로드한 파일은 다음 제한사항을 따라야 합니다.

  • 최대 파일 크기: 2MB
  • 허용된 미디어 MIME 유형: image/jpeg, image/png, application/octet-stream





이 요청에는 다음 범위 중 최소 하나를 사용하여 인증이 필요합니다. (인증 및 승인에 대해 자세히 알아보기)



아래 표는 이 쿼리가 지원하는 매개변수 목록입니다. 나열된 모든 매개변수는 쿼리 매개변수입니다.

매개변수 이름
필수 매개변수
videoId string
videoId 매개변수는 맞춤 동영상 미리보기 이미지가 제공되는 YouTube 동영상 ID를 지정합니다.
선택적 매개변수
onBehalfOfContentOwner string
이 매개변수는 제대로 인증된 요청에서만 사용할 수 있습니다. 참고: 이 매개변수는 YouTube 콘텐츠 파트너 전용입니다.

onBehalfOfContentOwner 매개변수는 요청의 승인 사용자 인증 정보가 매개변수 값에 지정된 콘텐츠 소유자를 대신하는 YouTube CMS 사용자를 확인함을 나타냅니다. 이 매개변수는 다양한 여러 YouTube 채널을 소유하고 관리하는 YouTube 콘텐츠 파트너 전용입니다. 이 매개변수로 콘텐츠 소유자는 각 개별 채널에 승인 사용자 인증 정보를 제공할 필요 없이 한 번 인증하여 모든 동영상 및 채널 데이터에 액세스할 수 있습니다. 사용자가 인증할 CMS 계정은 지정된 YouTube 콘텐츠 소유자에게 연결되어야 합니다.

요청 본문

이 메소드를 호출할 때 요청 본문을 제공하지 마세요.


성공하는 경우 이 메소드는 다음 구조로 응답 본문을 반환합니다.

  "kind": "youtube#thumbnailSetResponse",
  "etag": etag,
  "items": [
    thumbnails resource


다음 표는 이 리소스에 표시되는 속성을 정의합니다.

속성 이름
kind string
API 리소스의 유형입니다. 값은 youtube#thumbnailSetResponse가 됩니다.
etag etag
이 리소스의 Etag입니다.
items[] list
미리보기 이미지의 목록입니다.

참고: 아래의 코드 샘플은 지원되는 일부 프로그래밍 언어를 나타냅니다. 지원되는 언어 목록을 보려면 클라이언트 라이브러리 문서를 참조하세요.


PHP 클라이언트 라이브러리를 사용하는 예입니다.


 * This sample uploads and sets a custom thumbnail for a video.
 * 1. It uploads an image using the "Google_MediaFileUpload" class.
 * 2. It sets the uploaded image as a custom thumbnail to the video by
 *    calling the API's "youtube.thumbnails.set" method
 * @author Ibrahim Ulukaya

 * Library Requirements
 * 1. Install composer (
 * 2. On the command line, change to this directory (api-samples/php)
 * 3. Require the google/apiclient library
 *    $ composer require google/apiclient:~2.0
if (!file_exists(__DIR__ . '/vendor/autoload.php')) {
  throw new \Exception('please run "composer require google/apiclient:~2.0" in "' . __DIR__ .'"');

require_once __DIR__ . '/vendor/autoload.php';

 * You can acquire an OAuth 2.0 client ID and client secret from the
 * Google API Console <>
 * For more information about using OAuth 2.0 to access Google APIs, please see:
 * <>
 * Please ensure that you have enabled the YouTube Data API for your project.

$client = new Google_Client();
$redirect = filter_var('http://' . $_SERVER['HTTP_HOST'] . $_SERVER['PHP_SELF'],

// Define an object that will be used to make all API requests.
$youtube = new Google_Service_YouTube($client);

// Check if an auth token exists for the required scopes
$tokenSessionKey = 'token-' . $client->prepareScopes();
if (isset($_GET['code'])) {
  if (strval($_SESSION['state']) !== strval($_GET['state'])) {
    die('The session state did not match.');

  $_SESSION[$tokenSessionKey] = $client->getAccessToken();
  header('Location: ' . $redirect);

if (isset($_SESSION[$tokenSessionKey])) {

// Check to ensure that the access token was successfully acquired.
if ($client->getAccessToken()) {
  $htmlBody = '';

    // REPLACE this value with the video ID of the video being updated.
    $videoId = "VIDEO_ID";

    // REPLACE this value with the path to the image file you are uploading.
    $imagePath = "/path/to/file.png";

    // Specify the size of each chunk of data, in bytes. Set a higher value for
    // reliable connection as fewer chunks lead to faster uploads. Set a lower
    // value for better recovery on less reliable connections.
    $chunkSizeBytes = 1 * 1024 * 1024;

    // Setting the defer flag to true tells the client to return a request which can be called
    // with ->execute(); instead of making the API call immediately.

    // Create a request for the API's thumbnails.set method to upload the image and associate
    // it with the appropriate video.
    $setRequest = $youtube->thumbnails->set($videoId);

    // Create a MediaFileUpload object for resumable uploads.
    $media = new Google_Http_MediaFileUpload(

    // Read the media file and upload it chunk by chunk.
    $status = false;
    $handle = fopen($imagePath, "rb");
    while (!$status && !feof($handle)) {
      $chunk = fread($handle, $chunkSizeBytes);
      $status = $media->nextChunk($chunk);


    // If you want to make other calls after the file upload, set setDefer back to false

    $thumbnailUrl = $status['items'][0]['default']['url'];
    $htmlBody .= "<h3>Thumbnail Uploaded</h3><ul>";
    $htmlBody .= sprintf('<li>%s (%s)</li>',
    $htmlBody .= sprintf('<img src="%s">', $thumbnailUrl);
    $htmlBody .= '</ul>';

  } catch (Google_Service_Exception $e) {
    $htmlBody .= sprintf('<p>A service error occurred: <code>%s</code></p>',
  } catch (Google_Exception $e) {
    $htmlBody .= sprintf('<p>An client error occurred: <code>%s</code></p>',

  $_SESSION[$tokenSessionKey] = $client->getAccessToken();
} elseif ($OAUTH2_CLIENT_ID == 'REPLACE_ME') {
  $htmlBody = <<<END
  <h3>Client Credentials Required</h3>
    You need to set <code>\$OAUTH2_CLIENT_ID</code> and
    <code>\$OAUTH2_CLIENT_ID</code> before proceeding.
} else {
  // If the user hasn't authorized the app, initiate the OAuth flow
  $state = mt_rand();
  $_SESSION['state'] = $state;

  $authUrl = $client->createAuthUrl();
  $htmlBody = <<<END
<h3>Authorization Required</h3>
<p>You need to <a href="$authUrl">authorize access</a> before proceeding.<p>

<!doctype html>
<title>Claim Uploaded</title>


Python 클라이언트 라이브러리를 사용하는 예입니다.


import httplib2
import os
import sys

from apiclient.discovery import build
from apiclient.errors import HttpError
from oauth2client.client import flow_from_clientsecrets
from oauth2client.file import Storage
from import argparser, run_flow

# The CLIENT_SECRETS_FILE variable specifies the name of a file that contains
# the OAuth 2.0 information for this application, including its client_id and
# client_secret. You can acquire an OAuth 2.0 client ID and client secret from
# the Google API Console at
# Please ensure that you have enabled the YouTube Data API for your project.
# For more information about using OAuth2 to access the YouTube Data API, see:
# For more information about the client_secrets.json file format, see:
CLIENT_SECRETS_FILE = "client_secrets.json"

# This OAuth 2.0 access scope allows for full read/write access to the
# authenticated user's account.

# This variable defines a message to display if the CLIENT_SECRETS_FILE is
# missing.
WARNING: Please configure OAuth 2.0

To make this sample run you will need to populate the client_secrets.json file
found at:


with information from the API Console

For more information about the client_secrets.json file format, please visit:
""" % os.path.abspath(os.path.join(os.path.dirname(__file__),

def get_authenticated_service(args):
  flow = flow_from_clientsecrets(CLIENT_SECRETS_FILE,

  storage = Storage("%s-oauth2.json" % sys.argv[0])
  credentials = storage.get()

  if credentials is None or credentials.invalid:
    credentials = run_flow(flow, storage, args)


# Call the API's thumbnails.set method to upload the thumbnail image and
# associate it with the appropriate video.
def upload_thumbnail(youtube, video_id, file):

if __name__ == "__main__":
  # The "videoid" option specifies the YouTube video ID that uniquely
  # identifies the video for which the thumbnail image is being updated.
  argparser.add_argument("--video-id", required=True,
    help="ID of video whose thumbnail you're updating.")
  # The "file" option specifies the path to the thumbnail image file.
  argparser.add_argument("--file", required=True,
    help="Path to thumbnail image file.")
  args = argparser.parse_args()

  if not os.path.exists(args.file):
    exit("Please specify a valid file using the --file= parameter.")

  youtube = get_authenticated_service(args)
    upload_thumbnail(youtube, args.video_id, args.file)
  except HttpError, e:
    print "An HTTP error %d occurred:\n%s" % (e.resp.status, e.content)
    print "The custom thumbnail was successfully set."


아래 표에서는 이 메소드에 대한 호출에 응답하기 위해 API가 반환할 수 있는 오류 메시지를 식별합니다. 자세한 내용은 오류 메시지 설명서를 참조하세요.

오류 유형 오류 세부정보 설명
badRequest mediaBodyRequired 요청에 이미지 콘텐츠가 포함되어 있지 않습니다.
forbidden forbidden 지정된 동영상에 미리보기 이미지를 설정할 수 없습니다. 요청이 제대로 인증되지 않았을 수 있습니다.
forbidden forbidden 인증된 사용자에게 맞춤 동영상 미리보기 이미지를 업로드하고 설정할 수 있는 권한이 없습니다.
notFound videoNotFound 미리보기 이미지를 삽입하려는 동영상을 찾을 수 없습니다. 요청 videoId 매개변수 값이 올바른지 확인하세요.