Thumbnails API

The Thumbnails API allows you to create, generate, and manage AI-powered thumbnails programmatically.

Base URL

https://youthumb.ai/api/thumbnails

Endpoints Overview

Method	Endpoint	Description
POST	/thumbnails	Create a new thumbnail project
POST	/thumbnails/:projectId/start	Start generation
GET	/thumbnails/:projectId/status	Get generation status
GET	/thumbnails/:projectId/detailed-status	Get detailed status with images

POST /thumbnails

Create a new thumbnail project.

curl -X POST https://youthumb.ai/api/thumbnails \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Excited creator with bright yellow background",
    "presetKey": "mrbeast-viral"
  }'

Request Body

Parameter	Type	Required	Description
`prompt`	string	Yes	Description of the thumbnail (3-2000 chars)
`personId`	uuid	No	Person ID for face swap
`personName`	string	No	Person name (alternative to personId)
`presetKey`	string	No	Style preset (see Presets)
`templateId`	uuid	No	Template ID for style reference
`styleReferenceUrl`	url	No	External image URL as style reference
`youtubeUrl`	url	No	YouTube URL to extract thumbnail
`contentImages`	array	No	Additional images (max 5)
`title`	string	No	Text overlay (max 200 chars)
`projectName`	string	No	Project name (max 100 chars)
`advancedOptions`	object	No	Advanced generation options

Advanced Options

Option	Type	Values
`variations`	number	`1`, `2`, `3`, `4`
`faceExpression`	string	`neutral`, `happy`, `surprised`, `excited`, `serious`, `confident`, `keep-original`
`textPosition`	string	`top`, `center`, `bottom`, `none`, `keep-original`
`negativePrompt`	string	What to avoid (max 500 chars)
`clothingStyle`	string	`casual`, `professional`, `sporty`, `elegant`, `streetwear`, `keep-original`
`faceEnhancement`	string	`subtle`, `normal`, `enhanced`, `keep-original`
`backgroundBlur`	number	`0` - `100`

Response `201 Created`

{
  "success": true,
  "data": {
    "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "draft",
    "projectName": "Untitled Project",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

POST /thumbnails/:projectId/start

Start the AI generation process. This consumes credits.

curl -X POST https://youthumb.ai/api/thumbnails/:projectId/start \
  -H "x-api-key: your_api_key"

Override Options

Override options when starting:

{
  "prompt": "Override the original prompt",
  "advancedOptions": {
    "variations": 4
  }
}

Success Response `200 OK`

{
  "success": true,
  "data": {
    "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "processing",
    "creditsConsumed": 1,
    "message": "Generation started"
  }
}

Error Response `402 Payment Required`

{
  "success": false,
  "error": "Insufficient credits"
}

GET /thumbnails/:projectId/status

Get project status and jobs. Supports optional pagination and status filtering.

# Basic (returns all jobs, backward-compatible)
curl https://youthumb.ai/api/thumbnails/:projectId/status \
  -H "x-api-key: your_api_key"

# With pagination
curl "https://youthumb.ai/api/thumbnails/:projectId/status?page=1&limit=20" \
  -H "x-api-key: your_api_key"

# With status filter
curl "https://youthumb.ai/api/thumbnails/:projectId/status?status=completed&page=1&limit=10" \
  -H "x-api-key: your_api_key"

# Multi-status filter
curl "https://youthumb.ai/api/thumbnails/:projectId/status?status=pending,processing" \
  -H "x-api-key: your_api_key"

Query Parameters

Parameter	Type	Default	Description
`page`	number	`1`	Page number (starts at 1)
`limit`	number	`20`	Items per page (max 100)
`status`	string	—	Filter by job status. Comma-separated for multiple: `pending,processing`

Note: Without page or limit, all jobs are returned without pagination (backward-compatible behavior).

Response (without pagination)

{
  "success": true,
  "data": {
    "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "processing",
    "projectName": "My Thumbnail",
    "jobs": [
      {
        "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "status": "completed",
        "generatedFileUrl": "https://storage.youthumb.ai/thumbnails/result.png",
        "createdAt": "2024-01-15T10:31:00.000Z"
      }
    ]
  }
}

Response (with pagination)

{
  "success": true,
  "data": {
    "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "processing",
    "projectName": "My Thumbnail",
    "jobs": [
      {
        "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "status": "completed",
        "generatedFileUrl": "https://storage.youthumb.ai/thumbnails/result.png",
        "createdAt": "2024-01-15T10:31:00.000Z"
      }
    ],
    "pagination": {
      "total": 42,
      "page": 1,
      "limit": 20,
      "totalPages": 3
    }
  }
}

Status Values

Status	Description
`draft`	Project created, not started
`processing`	Generation in progress
`completed`	All jobs completed
`failed`	Generation failed

GET /thumbnails/:projectId/detailed-status

Get detailed status with all generated images.

curl https://youthumb.ai/api/thumbnails/:projectId/detailed-status \
  -H "x-api-key: your_api_key"

Detailed Response

{
  "success": true,
  "data": {
    "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "projectName": "My Thumbnail",
    "status": "completed",
    "summary": {
      "totalJobs": 1,
      "activeJobs": 0,
      "completedJobs": 1,
      "failedJobs": 0,
      "totalVariations": 4
    },
    "latestGeneratedFileUrl": "https://storage.youthumb.ai/thumbnails/result.png",
    "jobs": [
      {
        "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "status": "completed",
        "type": "thumbnail-generation",
        "userPrompt": "Excited creator with yellow background",
        "generatedFileUrl": "https://storage.youthumb.ai/thumbnails/result.png",
        "images": {
          "styleReference": [],
          "content": [],
          "faces": [
            {
              "id": "face-001",
              "url": "https://storage.youthumb.ai/faces/face.jpg",
              "name": "face.jpg"
            }
          ],
          "results": [
            {
              "id": "result-001",
              "url": "https://storage.youthumb.ai/results/var1.png",
              "width": 1280,
              "height": 720
            },
            {
              "id": "result-002",
              "url": "https://storage.youthumb.ai/results/var2.png",
              "width": 1280,
              "height": 720
            }
          ]
        },
        "personIds": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"],
        "createdAt": "2024-01-15T10:31:00.000Z"
      }
    ],
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Complete Workflow Example

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

// 1. POST - Create project
const create = await fetch(`${API}/thumbnails`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    prompt: 'Excited tech reviewer with product',
    presetKey: 'tech-review',
    advancedOptions: { variations: 2 }
  }),
});
const { data: project } = await create.json();

// 2. POST - Start generation
await fetch(`${API}/thumbnails/${project.projectId}/start`, {
  method: 'POST',
  headers: { 'x-api-key': process.env.YOUTHUMB_API_KEY },
});

// 3. GET - Poll status
let status = 'processing';
while (status === 'processing') {
  await new Promise(r => setTimeout(r, 3000));

  const res = await fetch(`${API}/thumbnails/${project.projectId}/status`, {
    headers: { 'x-api-key': process.env.YOUTHUMB_API_KEY },
  });
  const data = await res.json();
  status = data.data.status;
}

// 4. GET - Get results
const results = await fetch(
  `${API}/thumbnails/${project.projectId}/detailed-status`,
  { headers: { 'x-api-key': process.env.YOUTHUMB_API_KEY } }
);
const { data: final } = await results.json();

console.log('Generated images:', final.jobs[0].images.results);