---
title: "Set Media Thumbnail"
description: "Set a custom thumbnail for a video."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.speakai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Media Thumbnail

Use the Speak AI MCP server tool `set_media_thumbnail` to set a custom thumbnail for
a video.

## What does it do?

Set a custom thumbnail for a video. Send exactly one of imageUrl, imageBase64 or
atSeconds. The image must be JPEG, PNG or WebP and at most 10 MB; the type is judged
from the file bytes, not the name. atSeconds uses the video frame at that moment;
this tool waits up to 60 seconds for the frame and returns its url, or says it is
still processing (check later with `get_media_status`, which carries the thumbnail
field). Each call replaces the current custom thumbnail, and there is no way back to
the automatic one. Needs permission to edit the media. Errors: 400 bad input,
unsupported image, blocked link or failed frame; 413 image too large; 409 a frame is
already being made; 503 frame service busy, try again shortly.

## Parameters

`set_media_thumbnail` takes 4 parameters, 1 of them required.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `mediaId` | string | Yes | Unique identifier of the video |
| `imageUrl` | string | No | A public https link to a JPEG, PNG or WebP image of at most 10 MB. The server downloads it. |
| `imageBase64` | string | No | The image bytes in base64 (JPEG, PNG or WebP, at most 10 MB once decoded). A data:image/...;base64, prefix is allowed. |
| `atSeconds` | number | No | Use the video frame at this many seconds from the start. Values past the end use the last second. |

## Behaviour

The Speak AI MCP server publishes these behaviour hints for `set_media_thumbnail`.

- Can change data in your workspace.
- Can delete or overwrite data. Use with care.
- Repeating an identical call can have an extra effect.
- Can reach systems outside Speak AI.

## Related

- [Media](/mcp/tools/media/) lists the rest of the Media category.
- [Tool reference](/mcp/tools/) lists every Speak AI MCP server tool.
- [MCP server](/mcp/) covers setup, supported clients, and what agents can do once
  connected.

Source: https://docs.speakai.co/mcp/tools/media/set_media_thumbnail/index.mdx