YouTube expanded its publishing API on November 3 to support custom thumbnails for Shorts. Connected applications can submit a cover image after the video has finished processing. The update also adds a vertical thumbnail variant to the data YouTube returns. The change concerns tools that content teams use to manage publishing on a channel.
The thumbnail is attached after video processing
The thumbnails.set operation receives an image for an existing video ID. For a Short, YouTube requires the video to have processed successfully. If the image is submitted earlier, the service can receive the request without applying the thumbnail to the clip.
The video owner can read the processing stage from the data associated with the video. The processingStatus field in processingDetails can indicate that processing is underway, failed, succeeded or is no longer available. YouTube specifies the succeeded value as the point for attaching an image to Shorts. The data also includes progress estimates that the owner can access while processing is underway.
The videos.list method can return the processing section for videos requested by ID. The application specifies which sections of the resource the request should return. The same method can return content and visibility data when appropriate. Reading the resource and sending the image are separate operations, each with its own response. A read through this method uses one unit of API quota.
For interrupted transfers, the API supports resumable uploads. The service signals an incomplete upload with an HTTP 308 response and, if it has received part of the file, reports the byte range in the Range header. The application can continue from the next byte. On successful upload completion, the HTTP 201 response includes the newly created video resource. That confirmation provides the video ID, while processing status is retrieved separately.
Stages of publishing a Short through the API
- UploadYouTube receives the video file and publishing details.
- ProcessingThe application watches for successful processing.
- ThumbnailThe image is attached to the processed video.
The vertical format and the data the API returns
The thumbnail resource includes shortsAspectRatio for a Short with a custom image. It describes the 9:16 version, with the image address and width and height fields. The API reference says dimensions may be absent from the response. YouTube crops a Short's thumbnail to the portrait aspect ratio while processing the submitted image.
Video classification follows its own criteria. For standard channels, YouTube classifies square or vertical videos of up to three minutes uploaded from October 15, 2024 as Shorts. For Official Artist Channels and channels linked to a music content owner, the corresponding classification rule applies to uploads from December 8, 2025. The 9:16 ratio in the API update applies to the cover image, including when the video classified as a Short is square.
The documented limit for an image sent through thumbnails.set is 50 MB. The method accepts JPEG and PNG images. A successful response includes a list of thumbnails. The documentation specifies distinct responses for invalid image content, insufficient permissions, a video ID that cannot be found and too many recent uploads at channel level.
YouTube also offers Shorts thumbnail uploads through Studio on a computer for verified accounts. For that interface, the documentation recommends vertical images of 2,160 × 3,840 pixels and a minimum height of 640 pixels. These dimensions describe preparation of the image file, and the API property describes the variant the platform returns after the thumbnail is set.
The separate change to upload visibility
On November 2, YouTube removed the restriction that made videos uploaded through videos.insert from unverified API projects private. The rule dated from 2020 and tied changes to visibility to a project audit. Under the current behavior, when a request omits the privacy setting, the default is public, with exceptions determined by the creator's account settings.
YouTube retains three visibility states. A public video can appear in search results and recommendations. An unlisted video can be viewed and reshared by people who have its address. A private video's access is limited to its owner and selected people. In the default account settings for creators aged 13 to 17, videos are private.
Scheduled publishing keeps the video private until the selected date and time. YouTube Studio lets users choose a time zone for that scheduled time. The video's public page uses Pacific time for the displayed date, which can produce a different calendar day from the date shown in Studio. In this workflow, the publication time and the time processing finishes are separate information.
Channel permissions and separate quotas
Uploading a video through the API uses authorization with upload permissions for the account. For YouTube partners that manage several channels through its content management system, the method can receive the content owner and target channel separately. The notifySubscribers parameter controls whether subscribers are notified about the new video and is enabled by default, according to the upload method reference.
The default quota for videos.insert is 100 calls per day in the video uploads bucket. A call uses one unit from that bucket. Other operations share the default 10,000 units per day, except search, which also has its own quota. The thumbnail upload method costs approximately 50 units per request.
YouTube describes uploading as the stage when the file arrives on the platform and publishing as the point when the video becomes available according to its selected visibility. The owner can receive the results of copyright checks before release. In a workflow that prepares videos for several channels, each of these states can be tracked separately from confirmation that the thumbnail has been set.
