YouTube thumbnail

Changes the thumbnail of a video already on YouTube. To set one while posting, send thumbnail with the video instead (see YouTube).

Set a thumbnail

Send the image as a multipart thumbnail file, with the profile in user and the YouTube video_id:

curl -X POST https://api.reelspan.com/v1/youtube/thumbnail \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "video_id=aB3xYz12Q" \
  -F "[email protected]"

import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const out = await reelspan.request('POST', '/v1/youtube/thumbnail', {
  json: { user: 'my-brand', video_id: 'aB3xYz12Q', thumbnail_url: 'https://example.com/thumbnail.jpg' },
});

from reelspan import Reelspan

reelspan = Reelspan()
out = reelspan.request("POST", "/v1/youtube/thumbnail", json_body={
    "user": "my-brand",
    "video_id": "aB3xYz12Q",
    "thumbnail_url": "https://example.com/thumbnail.jpg",
})

{
  "success": true,
  "video_id": "aB3xYz12Q",
  "width": 1280,
  "height": 720,
  "thumbnails": {
    "default": { "url": "https://i.ytimg.com/vi/aB3xYz12Q/default.jpg", "width": 120, "height": 90 },
    "high": { "url": "https://i.ytimg.com/vi/aB3xYz12Q/hqdefault.jpg", "width": 480, "height": 360 },
    "maxres": { "url": "https://i.ytimg.com/vi/aB3xYz12Q/maxresdefault.jpg", "width": 1280, "height": 720 }
  }
}

width and height are those of the largest size YouTube made; thumbnails lists every size.

The image

Send one of these; when more than one is sent, the file wins, then the URL:

• thumbnail: the file, in a multipart/form-data body.
• thumbnail_url: a public https URL (in JSON or multipart).
• thumbnail_media_id: a photo uploaded earlier with kind=photo.

It must be JPEG, PNG, GIF or BMP and at most 2 MB. Reelspan doesn't keep the file afterwards; a thumbnail_media_id stays in your uploads.

Which video

• video_id and user (or profile_username): any video on the profile's connected YouTube channel, including ones uploaded outside Reelspan. post_id works in place of video_id.
• Or request_id: the Reelspan request that published the video.

Good to know

• A verified channel. YouTube allows custom thumbnails only on channels verified at youtube.com/verify. On other channels YouTube refuses with 403, which comes back as 502 youtube_forbidden.
• Shorts don't show custom thumbnails on YouTube, even when one is set.
• Thumbnails are the only change Reelspan can make to a published video: editing or deleting it needs a wider YouTube permission than the upload access Reelspan asks for.

Errors

Setting a thumbnail needs a key with the publish scope.