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 lists the rest of the Media category.
- Tool reference lists every Speak AI MCP server tool.
- MCP server covers setup, supported clients, and what agents can do once connected.