POST /v1/generate

Generate a thumbnail from a title. This is the only endpoint you need.

POST https://api.thumbapi.dev/v1/generate

Headers

Request Body

Legacy parameters (still accepted)

The following older parameter names continue to work — older SDKs and the WordPress plugin can keep sending them without changes:

You cannot combine photo + logo through the legacy imageStyle enum — use the new usePhoto / useLogo flags for that case.

Format Dimensions

Categories

Bias the generation toward a specific niche. The category influences both the reference grid search query and a soft final-tone hint appended to the prompt — it never overrides the references.

auto (default), tech-saas, business-finance, education-tutorial, fitness-wellness, medical-healthcare, lifestyle-vlog, food-cooking, travel, gaming, entertainment-comedy, news-commentary, creative-design.

Photo & Logo (independent flags)

usePhoto and useLogo are independent — you can use either, both, or neither.

• usePhoto: true — the API uses your saved Personal Photo, or the inline photoImage if you provide one. The photo is fed to the model so it integrates the face into the generated scene.
• useLogo: true — the API overlays your saved Logo onto the final image programmatically (sharp composite, never sent to the model). Position, size, and drop shadow come from your saved Logo config. To override, save a different config in the dashboard or pass logoImage inline.
• Both true — face in the scene + logo overlay in the corner.

If you set usePhoto: true (or useLogo: true) without inline data and have no saved asset, the API returns 400.

Custom Reference Sets

customAssetsId points to a 1–6 image set you uploaded as your own style template. When provided, the AI clones your set's style at 80–100% fidelity instead of auto-discovering YouTube references. The set's stored format wins — you don't need to send format separately (and it's ignored if you do).

Credit cost

Each generation deducts credits from your monthly plan quota. The cost depends on the model and which add-ons you enable:

Examples:

• Faceless 1K thumbnail → 10 credits
• 1K thumbnail with photo → 12 credits
• 2K thumbnail with photo + logo → 24 credits (20 + 2 + 2)
• 2K thumbnail with photo + logo + reference set → 26 credits

Your plan's monthly credit allowance:

Defaults: model: "sd" (1K), category: "auto". The 2K quality (model: "hd") is gated to Pro and Business plans — sending it on Free/Creator returns 403 UPGRADE_REQUIRED.

Example Requests

Faceless (default)

curl -X POST https://api.thumbapi.dev/v1/generate \
  -H "x-api-key: tb_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "10 Tips to Grow Your YouTube Channel",
    "format": "youtube",
    "category": "education-tutorial"
  }'

With saved photo

curl -X POST https://api.thumbapi.dev/v1/generate \
  -H "x-api-key: tb_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How I Built a $1M SaaS",
    "format": "youtube",
    "category": "business-finance",
    "usePhoto": true
  }'

Photo + logo (both)

curl -X POST https://api.thumbapi.dev/v1/generate \
  -H "x-api-key: tb_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My 2026 Annual Review",
    "format": "youtube",
    "usePhoto": true,
    "useLogo": true
  }'

Logo only, inline

curl -X POST https://api.thumbapi.dev/v1/generate \
  -H "x-api-key: tb_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Product Launch",
    "format": "instagram",
    "useLogo": true,
    "logoImage": "data:image/png;base64,iVBORw0KGgo..."
  }'

Custom reference set

curl -X POST https://api.thumbapi.dev/v1/generate \
  -H "x-api-key: tb_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Episode 47: The Future of AI",
    "customAssetsId": "ref_brand_v2"
  }'

2K render (Pro+)

curl -X POST https://api.thumbapi.dev/v1/generate \
  -H "x-api-key: tb_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Annual Report 2026",
    "format": "linkedin",
    "category": "business-finance",
    "model": "hd"
  }'

Response

{
  "image": "data:image/webp;base64,UklGRp4HAA...",
  "format": "youtube",
  "outputFormat": "webp"
}

Response Fields

Error Responses

See Error Codes for full details.

Common Mistakes

1. Asset toggle without a saved asset — usePhoto: true / useLogo: true requires either the saved asset or an inline photoImage / logoImage. Otherwise the API returns 400.
2. Invalid format value — must be exactly youtube, instagram, x, blogpost, or linkedin. No aliases.
3. Empty title — the title field must be a non-empty string (max 200 characters).
4. Logo too large — logoImage cap is 1 MB (smaller than the 2 MB photo cap, since logos compress well).
5. Sending format with customAssetsId — harmless but ignored. The reference set's stored format wins.

Next Steps

• Custom assets guide — in-depth guide to photos, logos, and reference sets
• Code examples — copy-paste snippets in 3 languages
• Rate limits — understand your quota
• Webhooks — async generation for high-volume use