POST /v1/generate
Generate a thumbnail from a title. This is the only endpoint you need.
POST https://api.thumbapi.dev/v1/generate
Headers
| Header | Required | Value |
|---|
Authorization | Yes | Bearer YOUR_API_KEY |
Content-Type | Yes | application/json |
Request Body
| Field | Type | Required | Description |
|---|
title | string | Yes | The title to generate a thumbnail for |
format | string | Yes | youtube | instagram | x | blogpost |
imageStyle | string | Yes | faceless | with-image | with-logo |
personImage | string | No | Base64-encoded image. Required if imageStyle is with-image or with-logo |
Format Dimensions
| Format | Width | Height |
|---|
youtube | 1280 | 720 |
blogpost | 1200 | 630 |
instagram | 1080 | 1080 |
x | 1600 | 900 |
Image Styles
faceless — text and graphic design, no people. Best for automated content.with-image — includes a person's photo. Send the photo as personImage (base64).with-logo — branded thumbnail with logo overlay. Send logo as personImage (base64).
Example Request
curl -X POST https://api.thumbapi.dev/v1/generate \
-H "Authorization: Bearer tb_live_abc123" \
-H "Content-Type: application/json" \
-d '{
"title": "10 Tips to Grow Your YouTube Channel",
"format": "youtube",
"imageStyle": "faceless"
}'
Response
{
"image": "data:image/webp;base64,UklGRp4HAA...",
"format": "youtube",
"dimensions": {
"width": 1280,
"height": 720
}
}
Response Fields
| Field | Type | Description |
|---|
image | string | Base64-encoded WebP image with data URI prefix |
format | string | The format that was used |
dimensions | object | width and height in pixels |
Error Responses
| Status | Cause |
|---|
400 | Missing or invalid title, format, or imageStyle |
401 | Missing or invalid API key |
429 | Rate limit or generation limit exceeded |
500 | Server error during generation |
See Error Codes for full details.
Common Mistakes
- Missing
personImage for with-image style — returns 400. If you choose with-image or with-logo, you must provide the base64 image.
- Invalid format value — must be exactly
youtube, instagram, x, or blogpost. No aliases.
- Empty title — the
title field must be a non-empty string.
Next Steps
