Quickstart

This guide will walk you through generating your first AI thumbnail using the API.

Prerequisites

An account with available credits
An API key (see Authentication)

Step 1: Verify Your API Key

First, verify that your API key is working:

curl https://yourdomain.com/api/v1/auth/verify \
  -H "Authorization: Bearer api_your_key_here"

You should receive a response with your organization details.

Step 2: Check Your Credits

Make sure you have credits available:

curl https://yourdomain.com/api/v1/account/credits \
  -H "Authorization: Bearer api_your_key_here"

Response:

{
  "data": {
    "tier": "creator",
    "credits": {
      "total": 45,
      "purchased": 10,
      "subscription": 35
    },
    "canGenerate": true,
    "billingCycle": "monthly"
  }
}

Step 3: Generate a Thumbnail

Now generate your first thumbnail:

curl -X POST https://yourdomain.com/api/v1/thumbnails \
  -H "Authorization: Bearer api_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A surprised person looking at their phone with a shocked expression, bright yellow background, bold text saying WOW"
  }'

Response:

{
  "data": {
    "id": "uuid-of-thumbnail",
    "imageUrl": "https://storage.example.com/thumbnails/abc123.png",
    "prompt": "A surprised person looking at..."
  }
}

Step 4: View Your Thumbnail

The imageUrl in the response is a permanent URL to your generated thumbnail. You can:

Download it directly
Use it in your application
View it in your dashboard

Step 5: Edit a Thumbnail

You can edit any image using the editing endpoints. For example, remove the background:

curl -X POST https://yourdomain.com/api/v1/thumbnails/edit/background-remove \
  -H "Authorization: Bearer api_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://storage.example.com/thumbnails/abc123.png"
  }'

Or apply a color enhancement preset (free, no credits needed):

curl -X POST https://yourdomain.com/api/v1/thumbnails/edit/color-enhance \
  -H "Authorization: Bearer api_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://storage.example.com/thumbnails/abc123.png",
    "preset": "cinematic",
    "intensity": "strong"
  }'

Next Steps

Now that you've generated your first thumbnail, try:

Editing Thumbnails - Use the editing endpoints to refine your thumbnails (face swap, background removal, color enhance, upscale, filters)
Using Reference Images - Pass referenceImageUrls when generating to match a visual style without creating a Style
Using a Style - Create a style from a reference image and apply it
Adding a Face - Upload face images for personalized thumbnails
Adding Brand Colors - Import a brand for consistent colors
Analyzing a Video - Get AI-generated thumbnail concepts for a YouTube video

Example: Full Workflow

Here's a complete example that analyzes a video and generates a thumbnail:

# 1. Analyze a YouTube video
curl -X POST https://yourdomain.com/api/v1/thumbnails/analyze \
  -H "Authorization: Bearer api_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }'
 
# Response includes thumbnail concepts with prompts
 
# 2. Generate a thumbnail using one of the concepts
curl -X POST https://yourdomain.com/api/v1/thumbnails \
  -H "Authorization: Bearer api_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The prompt from the concept above"
  }'

Analyzing without a YouTube link

If your source isn't a YouTube video — or the video is unlisted/private and the transcript can't be auto-fetched — send the transcript directly:

curl -X POST https://yourdomain.com/api/v1/thumbnails/analyze \
  -H "Authorization: Bearer api_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "transcript": "In this episode we break down how creators are using AI to...",
    "videoTitle": "How I built my SaaS in 30 days"
  }'

Provide exactly one of youtubeUrl or transcript. Transcripts must be at least 50 characters; videoTitle is optional.

Example: Generate with Reference Image

You can pass a reference image directly instead of creating a Style:

curl -X POST https://yourdomain.com/api/v1/thumbnails \
  -H "Authorization: Bearer api_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cooking tutorial thumbnail with vibrant colors",
    "referenceImageUrls": ["https://example.com/style-reference.jpg"]
  }'

Code Examples

JavaScript/Node.js

const API_KEY = process.env.YT_AI_THUMBNAIL_API_KEY;
const BASE_URL = 'https://yourdomain.com/api/v1';
 
async function generateThumbnail(prompt, options = {}) {
  const response = await fetch(`${BASE_URL}/thumbnails`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ prompt, ...options })
  });
 
  const { data } = await response.json();
  return data;
}
 
// Basic generation
const thumbnail = await generateThumbnail(
  'Excited gamer celebrating a victory, neon lights, gaming setup'
);
console.log('Thumbnail URL:', thumbnail.imageUrl);
 
// Generation with reference image
const styled = await generateThumbnail(
  'Travel vlog thumbnail, tropical destination',
  { referenceImageUrls: ['https://example.com/style-ref.jpg'] }
);
 
// Edit an existing thumbnail
async function editThumbnail(imageUrl, prompt) {
  const response = await fetch(`${BASE_URL}/thumbnails/edit`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ imageUrl, prompt })
  });
  return (await response.json()).data;
}

Python

import os
import requests
 
API_KEY = os.environ.get('YT_AI_THUMBNAIL_API_KEY')
BASE_URL = 'https://yourdomain.com/api/v1'
 
def generate_thumbnail(prompt, **kwargs):
    response = requests.post(
        f'{BASE_URL}/thumbnails',
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json'
        },
        json={'prompt': prompt, **kwargs}
    )
    return response.json()['data']
 
def edit_thumbnail(image_url, prompt):
    response = requests.post(
        f'{BASE_URL}/thumbnails/edit',
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json'
        },
        json={'imageUrl': image_url, 'prompt': prompt}
    )
    return response.json()['data']
 
# Basic generation
thumbnail = generate_thumbnail(
    'Excited gamer celebrating a victory, neon lights, gaming setup'
)
print(f"Thumbnail URL: {thumbnail['imageUrl']}")
 
# Edit an existing thumbnail
edited = edit_thumbnail(
    thumbnail['imageUrl'],
    'Make the background more dramatic with lightning'
)
print(f"Edited URL: {edited['imageUrl']}")

Authentication Endpoints