REST API

The Thumbfa.st API lets you integrate thumbnail generation into any application.

Base URL: https://thumbfa.st/api/v1

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer tf_your_api_key_here

Get your API key from Settings → Developer in your dashboard.

Tool Discovery

List All Tools

GET /api/v1/tools

Returns all available tools with their schemas.

Response:

{
  "tools": [
    {
      "name": "generate_thumbnail",
      "description": "Generate YouTube thumbnails from a text prompt",
      "category": "generation",
      "endpoint": "/api/v1/tools/generate_thumbnail",
      "method": "POST",
      "meta": {
        "creditCost": 1,
        "rateLimit": 10
      }
    }
  ],
  "totalCount": 21
}

Making Requests

Tool Execution

All tools are available at:

POST /api/v1/tools/{toolName}

Example: Generate a thumbnail

curl -X POST https://thumbfa.st/api/v1/tools/generate_thumbnail \
  -H "Authorization: Bearer tf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A YouTuber looking shocked at their laptop",
    "count": 2,
    "model": "gemini"
  }'

Response:

{
  "success": true,
  "data": {
    "promptId": "prompt_abc123",
    "generationId": "gen_xyz789",
    "count": 2,
    "message": "Generating 2 thumbnail(s). Use get_generation_status to check progress."
  }
}

Error Handling

All errors follow this format:

{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {}
}

Common Error Codes

Rate Limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1706526000

Code Examples

Node.js / TypeScript

const response = await fetch(
  "https://thumbfa.st/api/v1/tools/generate_thumbnail",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer tf_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "A YouTuber looking shocked",
      count: 2,
      model: "gemini",
    }),
  },
);

const result = await response.json();
console.log(result.data.generationId);

Python

import requests

response = requests.post(
    "https://thumbfa.st/api/v1/tools/generate_thumbnail",
    headers={
        "Authorization": "Bearer tf_your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "prompt": "A YouTuber looking shocked",
        "count": 2,
        "model": "gemini",
    },
)

result = response.json()
print(result["data"]["generationId"])

cURL

curl -X POST https://thumbfa.st/api/v1/tools/generate_thumbnail \
  -H "Authorization: Bearer tf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A YouTuber looking shocked",
    "count": 2,
    "model": "gemini"
  }'

Thumbnail Costs

Check your balance anytime:

curl https://thumbfa.st/api/v1/tools/get_credits \
  -H "Authorization: Bearer tf_your_api_key"

Webhooks (Coming Soon)

Receive notifications when thumbnails are generated. Contact support if you need early access.

Next Steps

• MCP Integration - Connect to AI assistants
• Tools Reference - Detailed tool documentation