Set YouTube Thumbnail

Set (or replace) the custom thumbnail of a video that is already on YouTube — for example a Short you published without one, or a video whose thumbnail you want to A/B test. The video must belong to the YouTube channel connected to the profile.

Endpoint

POST /api/uploadposts/youtube/thumbnail

Headers

Name	Value	Description
Authorization	Apikey your-api-key-here	Your API key

Parameters

Send multipart/form-data (for a file) or JSON (for a URL).

Name	Type	Required	Description
user	String	Yes	Profile name whose YouTube channel owns the video
video_id	String	Yes	YouTube video ID (the post_id returned by the upload, or the v= value of the video URL)
thumbnail	File	One of the two	Image file. JPG, PNG, GIF or BMP, max 2 MB. YouTube recommends 1280×720 (16:9) for videos and 1080×1920 (9:16) for Shorts.
thumbnail_url	String	One of the two	Public URL of the image instead of a file

Example Request (file)

curl -X POST https://api.upload-post.com/api/uploadposts/youtube/thumbnail \
  -H "Authorization: Apikey your-api-key-here" \
  -F "user=my_profile" \
  -F "video_id=dQw4w9WgXcQ" \
  -F "thumbnail=@/path/to/thumbnail.jpg"

Example Request (URL)

curl -X POST https://api.upload-post.com/api/uploadposts/youtube/thumbnail \
  -H "Authorization: Apikey your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"user": "my_profile", "video_id": "dQw4w9WgXcQ", "thumbnail_url": "https://example.com/thumbnail.jpg"}'

Success Response

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

Error Responses

Status	When
400	Missing user/video_id, no thumbnail provided, not an image, unsupported format or over 2 MB
401	Invalid API key, or the YouTube token needs reconnecting
403	YouTube refused it — most often the channel is not verified (custom thumbnails require a verified channel)
404	The video does not exist or does not belong to the connected channel
429	YouTube API quota exhausted for today

The error field carries YouTube's reason in plain language; youtube_status is the raw status YouTube returned.

Notes

• Thumbnails can take a few minutes to refresh on YouTube's CDN.
• You can also send thumbnail / thumbnail_url directly on Upload Video to set it during the upload; this endpoint is for videos that are already published.

Related Endpoints

• Upload Video
• Unpublish Post