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

Next Steps