Templates API | YouThumbAI Documentation

The Templates API provides access to YouThumbAI's library of style reference templates. Templates are curated images that serve as visual references for the AI when generating thumbnails.

Concept

A Template in YouThumbAI is:

A pre-made style reference image
Categorized by content type (gaming, tech, lifestyle, etc.)
Can be featured (recommended) or regular
Used to guide the AI's visual style during generation

When you use a template, the AI:

Analyzes the composition and layout
Extracts color schemes and visual style
Applies similar aesthetics to your generated thumbnail
Swaps in your face while maintaining the style

List Templates

Retrieves available templates with optional filtering.

GET /api/templates

Query Parameters

Parameter	Type	Default	Description
`category`	string	-	Filter by category
`isFeatured`	boolean	-	Filter featured templates only
`page`	number	1	Page number
`limit`	number	20	Results per page (max 100)

All Templates:

curl "https://youthumb.ai/api/templates" \
  -H "x-api-key: your_api_key"

Featured Gaming Templates:

curl "https://youthumb.ai/api/templates?category=gaming&isFeatured=true" \
  -H "x-api-key: your_api_key"

Paginated:

curl "https://youthumb.ai/api/templates?page=2&limit=10" \
  -H "x-api-key: your_api_key"

List Templates Response

{
  "success": true,
  "data": {
    "templates": [
      {
        "id": "template-uuid-1",
        "name": "MrBeast Style Reaction",
        "description": "High energy reaction with bold colors",
        "category": "reaction",
        "imageUrl": "https://...",
        "thumbnailUrl": "https://...",
        "isFeatured": true,
        "tags": ["reaction", "viral", "colorful"],
        "createdAt": "2024-01-01T00:00:00.000Z"
      },
      {
        "id": "template-uuid-2",
        "name": "Tech Review Clean",
        "description": "Professional product showcase",
        "category": "tech",
        "imageUrl": "https://...",
        "thumbnailUrl": "https://...",
        "isFeatured": true,
        "tags": ["tech", "product", "clean"],
        "createdAt": "2024-01-02T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "totalPages": 3
    }
  }
}

Get Template Details

Retrieves full details for a specific template.

GET /api/templates/{id}

Parameter	Type	Description
`id`	string (UUID)	Template ID

curl "https://youthumb.ai/api/templates/template-uuid-1" \
  -H "x-api-key: your_api_key"

Template Details Response

{
  "success": true,
  "data": {
    "id": "template-uuid-1",
    "name": "MrBeast Style Reaction",
    "description": "High energy reaction thumbnail perfect for viral content. Features bold colors, expressive face placement, and attention-grabbing composition.",
    "category": "reaction",
    "imageUrl": "https://...",
    "thumbnailUrl": "https://...",
    "isFeatured": true,
    "tags": ["reaction", "viral", "colorful", "mrbeast"],
    "metadata": {
      "style": "energetic",
      "colorPalette": ["#FF0000", "#FFFF00", "#00FF00"],
      "facePosition": "center-right"
    },
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-10T00:00:00.000Z"
  }
}

Error: Template Not Found

{
  "success": false,
  "error": "Template not found"
}

Status Code: 404 Not Found

Using Templates in Thumbnail Generation

When creating a thumbnail, reference a template using its ID:

{
  "prompt": "Shocked reaction to unbelievable news",
  "templateId": "template-uuid-1",
  "personId": "your-person-id"
}

The AI will use the template's style while incorporating:

Your face (from the person profile)
Your specific prompt modifications
Any advanced options you specify

Template vs Style Reference URL

Method	Use Case
`templateId`	Use a curated YouThumbAI template
`styleReferenceUrl`	Use any external image URL as reference
`youtubeUrl`	Extract a YouTube video's thumbnail as reference

You can use one of these options per request.

Common Categories

Category	Description
`reaction`	Reaction and commentary videos
`gaming`	Gaming, esports, streams
`tech`	Technology reviews and tutorials
`vlog`	Vlogs and lifestyle content
`tutorial`	Educational and how-to content
`challenge`	Challenges and experiments
`cinematic`	Movie-style dramatic thumbnails

Complete Example: JavaScript

const API = 'https://youthumb.ai/api';
const headers = { 'x-api-key': process.env.YOUTHUMB_API_KEY };

// List featured templates
async function getFeaturedTemplates(category = null) {
  const params = new URLSearchParams({ isFeatured: 'true' });
  if (category) params.append('category', category);

  const response = await fetch(`${API}/templates?${params}`, { headers });
  return response.json();
}

// Get template details
async function getTemplate(templateId) {
  const response = await fetch(`${API}/templates/${templateId}`, { headers });
  return response.json();
}

// Generate thumbnail with template
async function generateWithTemplate(templateId, prompt, personId) {
  const response = await fetch(`${API}/thumbnails`, {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({ templateId, prompt, personId }),
  });
  return response.json();
}

// Usage
const templates = await getFeaturedTemplates('gaming');
console.log('Gaming templates:', templates.data.templates.length);

const firstTemplate = templates.data.templates[0];
const thumbnail = await generateWithTemplate(
  firstTemplate.id,
  'Victory celebration after winning the tournament',
  'my-person-id'
);