ThumbAPI logoThumbAPI

Quickstart — First Thumbnail in 5 Minutes

This guide gets you from zero to a generated thumbnail as fast as possible. You need: an internet connection and a terminal.

Step 1: Get Your API Key

Sign up at thumbapi.dev. Your API key is created automatically. Find it in the dashboard under API Keys.

Your key looks like: tb_live_abc123def456...

Or use the public test key to verify your setup without burning credits:

x-api-key: thumbapi_test

The test key returns a static placeholder image, useful for confirming your code or workflow is wired up correctly before switching to your real key.

Step 2: Make Your First Request

cURL

curl -X POST https://api.thumbapi.dev/v1/generate \
  -H "x-api-key: tb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How to Build a SaaS in 2026",
    "format": "youtube",
    "category": "tech-saas"
  }'

JavaScript (Node.js)

const response = await fetch("https://api.thumbapi.dev/v1/generate", {
  method: "POST",
  headers: {
    "x-api-key": process.env.THUMBAPI_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "How to Build a SaaS in 2026",
    format: "youtube",
    category: "tech-saas",
  }),
});

const { image, format, outputFormat } = await response.json();
// image is a base64 WebP string

Python

import requests
import os

response = requests.post(
    "https://api.thumbapi.dev/v1/generate",
    headers={
        "x-api-key": os.environ['THUMBAPI_KEY'],
        "Content-Type": "application/json",
    },
    json={
        "title": "How to Build a SaaS in 2026",
        "format": "youtube",
        "category": "tech-saas",
    },
)

data = response.json()
# data["image"] is a base64 WebP string

Step 3: Save the Image

The response image field contains a base64-encoded WebP image. To save it to disk:

Node.js

import { writeFileSync } from "fs";

const base64Data = image.replace(/^data:image\/webp;base64,/, "");
writeFileSync("thumbnail.webp", base64Data, "base64");

Python

import base64

base64_data = data["image"].split(",")[1]
with open("thumbnail.webp", "wb") as f:
    f.write(base64.b64decode(base64_data))

What's in the Response

FieldTypeDescription
imagestringBase64-encoded WebP or PNG image (data:image/webp;base64,...)
formatstringThe format used (youtube, blogpost, instagram, x, linkedin)
outputFormatstringwebp (default) or png
generationIdstringStable ID for this generation — use it for feedback endpoints and dashboard logs
imageUrlstringPublic Cloudflare R2 CDN link to the same image. Use it to download or hand off without decoding the inline base64

Next Steps