Estamos atualizando a API Data para corresponder à forma como o YouTube conta as visualizações dos Shorts.
Saiba mais
Thumbnails
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Um recurso thumbnail identifica diferentes tamanhos de imagens em miniatura associados a um recurso. Observe as seguintes características das imagens em miniatura:
- A propriedade
snippet.thumbnails de um recurso é um objeto que identifica as imagens em miniatura disponíveis para esse recurso. - Um recurso
thumbnail contém uma série de objetos. O nome de cada objeto (default, medium, high etc.) se refere ao tamanho da imagem em miniatura. - Diferentes tipos de recursos podem suportar diferentes tamanhos de imagens em miniatura.
- Diferentes tipos de recursos podem definir tamanhos diferentes para imagens em miniatura com o mesmo nome. Por exemplo, a imagem em miniatura
default de um recurso video geralmente tem 120 x 90 pixels, e a imagem em miniatura default de um recurso channel geralmente tem 88 x 88 pixels. - Recursos do mesmo tipo ainda podem ter diferentes tamanhos de imagem em miniatura para determinadas imagens, dependendo da resolução da imagem original ou do conteúdo carregado no YouTube. Por exemplo, um vídeo em HD pode apoiar miniaturas de resolução maior que vídeos não HD.
- Cada objeto que contém informações sobre o tamanho de uma imagem em miniatura tem uma propriedade
width e uma propriedade height. No entanto, as propriedades de largura e altura podem não ser retornadas para essa imagem. - Se uma imagem em miniatura carregada não corresponder às dimensões necessárias, a imagem será redimensionada para corresponder ao tamanho correto, sem alteração de sua proporção. A imagem não é cortada, mas pode incluir barras pretas para que o tamanho fique correto.
Métodos
A API é compatível com os seguintes métodos para recursos thumbnails:
- set
- Envia uma miniatura de vídeo personalizada para o YouTube e a define para um vídeo.
Representação de recurso
A estrutura JSON a seguir mostra o formato de um recurso thumbnails:
{
"default": {
"url": string,
"width": unsigned integer,
"height": unsigned integer
},
"medium": {
"url": string,
"width": unsigned integer,
"height": unsigned integer
},
"high": {
"url": string,
"width": unsigned integer,
"height": unsigned integer
},
"standard": {
"url": string,
"width": unsigned integer,
"height": unsigned integer
},
"maxres": {
"url": string,
"width": unsigned integer,
"height": unsigned integer
}
}
Propriedades
A tabela a seguir define as propriedades que aparecem neste recurso:
| Propriedades |
default |
object
A imagem de miniatura padrão. A miniatura padrão para um vídeo ou um recurso que se refere a um vídeo, como um item da playlist ou o resultado da pesquisa, tem 120 px de largura e 90px de altura. A miniatura padrão de um canal tem 88 px de largura e 88 px de altura. |
default.url |
string
O URL da imagem. |
default.width |
unsigned integer
A largura da imagem. |
default.height |
unsigned integer
A altura da imagem. |
medium |
object
Uma versão de maior resolução da imagem em miniatura. Para um vídeo (ou um recurso que se refira a um vídeo), esta imagem tem 320 px de largura e 180 px de altura. Para um canal, esta imagem tem 240 px de largura e 240 px de altura. |
medium.url |
string
O URL da imagem. |
medium.width |
unsigned integer
A largura da imagem. |
medium.height |
unsigned integer
A altura da imagem. |
high |
object
Uma versão de alta resolução da imagem em miniatura. Para um vídeo (ou um recurso que se refira a um vídeo), esta imagem tem 480 px de largura e 360 px de altura. Para um canal, esta imagem tem 800 px de largura e 800 px de altura. |
high.url |
string
O URL da imagem. |
high.width |
unsigned integer
A largura da imagem. |
high.height |
unsigned integer
A altura da imagem. |
standard |
object
Uma versão da imagem em miniatura com resolução ainda maior do que a imagem de resolução high. Essa imagem está disponível para alguns vídeos e outros recursos que se referem a vídeos, como itens de playlist ou resultados da pesquisa. Esta imagem tem 640 px de largura e 480 px de altura. |
standard.url |
string
O URL da imagem. |
standard.width |
unsigned integer
A largura da imagem. |
standard.height |
unsigned integer
A altura da imagem. |
maxres |
object
A versão de maior resolução da imagem em miniatura. Esse tamanho de imagem está disponível para alguns vídeos e outros recursos que se referem a vídeos, como itens de playlist ou resultados da pesquisa. Esta imagem tem 1.280 px de largura e 720 px de altura. |
maxres.url |
string
O URL da imagem. |
maxres.width |
unsigned integer
A largura da imagem. |
maxres.height |
unsigned integer
A altura da imagem. |
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2025-08-21 UTC.
[null,null,["Última atualização 2025-08-21 UTC."],[[["\u003cp\u003eA resource's \u003ccode\u003esnippet.thumbnails\u003c/code\u003e property contains an object, and each of these objects has properties such as \u003ccode\u003edefault\u003c/code\u003e, \u003ccode\u003emedium\u003c/code\u003e, and \u003ccode\u003ehigh\u003c/code\u003e, which identify the different available thumbnail image sizes for that specific resource.\u003c/p\u003e\n"],["\u003cp\u003eThumbnail image sizes can vary significantly between different resource types (e.g., videos vs. channels), and even among resources of the same type, based on the resolution of the original uploaded content.\u003c/p\u003e\n"],["\u003cp\u003eEach thumbnail image size object contains a \u003ccode\u003eurl\u003c/code\u003e, \u003ccode\u003ewidth\u003c/code\u003e, and \u003ccode\u003eheight\u003c/code\u003e property, but the width and height may not always be returned.\u003c/p\u003e\n"],["\u003cp\u003eWhen a custom thumbnail image is uploaded, it's resized to match the required dimensions without changing its aspect ratio, which may result in black bars being added.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003ethumbnails\u003c/code\u003e resource offers various image size options, such as \u003ccode\u003edefault\u003c/code\u003e, \u003ccode\u003emedium\u003c/code\u003e, \u003ccode\u003ehigh\u003c/code\u003e, \u003ccode\u003estandard\u003c/code\u003e, and \u003ccode\u003emaxres\u003c/code\u003e, each with distinct resolutions to accommodate different display needs.\u003c/p\u003e\n"]]],["Thumbnail resources define various image sizes (`default`, `medium`, `high`, etc.) for different resource types. Image dimensions vary by resource type and resolution. The `thumbnails` resource is an object within `snippet.thumbnails` that holds size-specific objects, each with `url`, `width`, and `height` properties. The `set` method allows uploading a custom video thumbnail. When the dimensions don't match, the image is resized, maintaining its aspect ratio, with possible added black bars.\n"],null,["# Thumbnails\n\nA **thumbnail** resource identifies different thumbnail image sizes associated with a resource. Please note the following characteristics of thumbnail images:\n\n- A resource's `snippet.thumbnails` property is an object that identifies the thumbnail images available for that resource.\n- A `thumbnail` resource contains a series of objects. The name of each object (`default`, `medium`, `high`, etc.) refers to the thumbnail image size.\n- Different types of resources may support different thumbnail image sizes.\n- Different types of resources may define different sizes for thumbnail images with the same name. For example, the `default` thumbnail image for a `video` resource is typically 120px by 90px, and the `default` thumbnail image for a `channel` resource is typically 88px by 88px.\n- Resources of the same type may still have different thumbnail image sizes for certain images depending on the resolution of the original image or content uploaded to YouTube. For example, an HD video may support higher resolution thumbnails than non-HD videos.\n- Each object that contains information about a thumbnail image size has a `width` property and a `height` property. However, the width and height properties may not be returned for that image.\n- If an uploaded thumbnail image does not match the required dimensions, the image is resized to match the correct size without changing its aspect ratio. The image is not cropped, but may include black bars so that the size is correct.\n\n\u003cbr /\u003e\n\nMethods\n-------\n\nThe API supports the following methods for `thumbnails` resources:\n\n[set](/youtube/v3/docs/thumbnails/set)\n: Uploads a custom video thumbnail to YouTube and sets it for a video.\n\nResource representation\n-----------------------\n\nThe following JSON structure shows the format of a `thumbnails` resource: \n\n```text\n{\n \"default\": {\n \"url\": string,\n \"width\": unsigned integer,\n \"height\": unsigned integer\n },\n \"medium\": {\n \"url\": string,\n \"width\": unsigned integer,\n \"height\": unsigned integer\n },\n \"high\": {\n \"url\": string,\n \"width\": unsigned integer,\n \"height\": unsigned integer\n },\n \"standard\": {\n \"url\": string,\n \"width\": unsigned integer,\n \"height\": unsigned integer\n },\n \"maxres\": {\n \"url\": string,\n \"width\": unsigned integer,\n \"height\": unsigned integer\n }\n}\n```\n\n### Properties\n\nThe following table defines the properties that appear in this resource:\n\n| Properties ||\n|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `default` | `object` The default thumbnail image. The default thumbnail for a video -- or a resource that refers to a video, such as a playlist item or search result -- is 120px wide and 90px tall. The default thumbnail for a channel is 88px wide and 88px tall. |\n| default.`url` | `string` The image's URL. |\n| default.`width` | `unsigned integer` The image's width. |\n| default.`height` | `unsigned integer` The image's height. |\n| `medium` | `object` A higher resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 320px wide and 180px tall. For a channel, this image is 240px wide and 240px tall. |\n| medium.`url` | `string` The image's URL. |\n| medium.`width` | `unsigned integer` The image's width. |\n| medium.`height` | `unsigned integer` The image's height. |\n| `high` | `object` A high resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 480px wide and 360px tall. For a channel, this image is 800px wide and 800px tall. |\n| high.`url` | `string` The image's URL. |\n| high.`width` | `unsigned integer` The image's width. |\n| high.`height` | `unsigned integer` The image's height. |\n| `standard` | `object` An even higher resolution version of the thumbnail image than the `high` resolution image. This image is available for some videos and other resources that refer to videos, like playlist items or search results. This image is 640px wide and 480px tall. |\n| standard.`url` | `string` The image's URL. |\n| standard.`width` | `unsigned integer` The image's width. |\n| standard.`height` | `unsigned integer` The image's height. |\n| `maxres` | `object` The highest resolution version of the thumbnail image. This image size is available for some videos and other resources that refer to videos, like playlist items or search results. This image is 1280px wide and 720px tall. |\n| maxres.`url` | `string` The image's URL. |\n| maxres.`width` | `unsigned integer` The image's width. |\n| maxres.`height` | `unsigned integer` The image's height. |"]]
