---
title: "A frame of a video plus words (tool render_thumbnail). Schema on GET /api/tools."
method: POST
path: "/api/thumbnails"
---

# A frame of a video plus words (tool render_thumbnail). Schema on GET /api/tools.

`POST /api/thumbnails`

## Request

- Base URL: `https://shapelessai.com`
- URL: `https://shapelessai.com/api/thumbnails`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shapelessai.com/api/auth/mcp/authorize`, token URL `https://shapelessai.com/api/auth/mcp/token`, scopes: `write`)

## Request body

- object
  - `video_key` string, required: The finished video (mediaKey from edit_footage or videoKey from render_video_project).
  - `frame_at` number, required: Seconds into the video (or into frame_key) to take the face from.
  - `frame_key` string: A clip to take the frame from instead, at its own resolution: the take behind the cut. frame_at then counts on it.
  - `headline` string, required: Three to five words, not the title. *Stars* mark the accent words: "I hired *an AI*".
  - `picture_key` string: One picture at most (an image media key): the product, the post, the number, the company's mark or the face of the person the video is about.
  - `accent` string: Hex colour of the starred words. Defaults to the cut's accent.
  - `foreground` string: Hex colour of the words. Default white.
  - `outline` string: Hex colour of the contour and the scrim behind the words. Default near-black.
  - `budgetUsd` number: The most this call may spend, in USD (default 2, max 10). Held while the tool runs, released after.

## Response `200`

OK

- ToolResult
  - `tool` string, required
  - `output` unknown, required
  - `media` object[], required: Every media key the output names, with the URL that streams it (read scope). Put a key on a post's mediaKeys.
    - `key` string
    - `url` string, uri
  - `chargedUsd` number, required

## Other responses

- `400`: The input does not match the tool's schema; the message names the field.
- `401`: No credential, or not valid.
- `402`: Not enough credit to hold budgetUsd, or the call costs more than budgetUsd.
- `403`: The key is missing the "write" scope.
- `404`: No such tool on this deployment.
- `422`: The tool refused this input; nothing was charged.
- `429`: Over the key's rate limit (600 requests an hour).
- `502`: The tool failed; nothing was charged.

---

[API](https://skmtc.dev/shapelessai/apis/shapeless-api.md) · [All operations](https://skmtc.dev/shapelessai/apis/shapeless-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shapelessai/apis/shapeless-api/revisions/fae8f701d466?raw)