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.

bash

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 6)
`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`

json

{
  "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.

bash

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

Override Options

Override options when starting:

json

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

Success Response `200 OK`

json

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

Error Response `402 Payment Required`

json

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

GET /thumbnails/:projectId/status

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

bash

# 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)

json

{
  "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)

json

{
  "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.

bash

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

Detailed Response

json

{
  "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

javascript

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);

Library, favorites and trash

Discover existing projects before creating another thumbnail. GET /api/thumbnails and list_thumbnail_projects accept search, status, favorite and deleted. Lists use page (starting at 1) and limit (1–100, default 20); filters apply before pagination. favorite=false selects non-favorites and deleted=true selects trashed projects. Favorites are shared by the selected organization. Send {"isFavorite":true} or {"isFavorite":false} explicitly; retries do not toggle the state. Rename with {"projectName":"New title"}. Library management costs no credits. MCP reads require mcp:read and Read access; mutations require mcp:generate and Generation access, plus the account's normal permissions. Trashing an entire project is restricted to administrators. Normal lists and detail hide deleted jobs and deleted parent projects. list_generations returns completed results across visible thumbnail projects, including every variation image in each job’s results array. Trash listing accepts kind=projects or kind=jobs (individually deleted jobs, including those under deleted parents). There is no permanent deletion. Restore the project first, then any individually deleted jobs. Project restoration sets its status to completed and does not restore its children. Project deletedAt is derived from updatedAt; it is not an immutable historical deletion timestamp. A job has its own stored deletedAt. Repeated trash/restore requests preserve timestamps when already in the requested state. Active jobs and projects with active jobs cannot be trashed (409). Restoring a job under a deleted parent also returns 409. Invalid payloads return 400, insufficient permissions 403, and unknown or foreign-organization identifiers 404. GET /api/thumbnails/:projectId, /detailed-status, /status and get_generation share details: project metadata, isFavorite, full-project summary, latest result, job metadata, grouped images and person IDs. jobs[].results and top-level activeJobs remain available. Without query options all visible jobs are returned; page or limit opts into bounded job pages. A comma-separated status alone filters all visible jobs without pagination, preserving existing clients. Summary and latest result always describe the whole visible project.

REST	MCP	Parameters
`GET /api/thumbnails`	`list_thumbnail_projects`	`page, limit, search, status, favorite, deleted`
`GET /api/thumbnails/:projectId`	`get_generation`	`summary?, page?, limit?, status?`
`PATCH /api/thumbnails/:projectId`	`update_thumbnail_project`	`projectName`
`GET /api/thumbnails/results`	`list_generations`	`page, limit, favorite, projectId`
`PUT /api/thumbnails/:projectId/favorite`	`set_project_favorite`	`isFavorite`
`PUT /api/thumbnails/jobs/:jobId/favorite`	`set_generation_favorite`	`isFavorite`
`DELETE /api/thumbnails/:projectId`	`trash_thumbnail_project`	`projectId`
`POST /api/thumbnails/:projectId/restore`	`restore_thumbnail_project`	`projectId`
`DELETE /api/thumbnails/jobs/:jobId`	`trash_generation`	`jobId`
`POST /api/thumbnails/jobs/:jobId/restore`	`restore_generation`	`jobId`
`GET /api/thumbnails/trash`	`list_trash`	`kind=projects / jobs, page, limit`

json

{"favorite":true,"page":1,"limit":20}

Attempts, iteration and retry

POST /api/thumbnails/:projectId/start and start_generation keep the same project. Optional overrides: prompt, personId (null clears), presetKey, templateId, styleReferenceUrl, youtubeUrl, sourceResultId, contentImages ([] clears), title ("" clears), and advancedOptions. Omitted fields retain project defaults; options merge. Overrides affect only this attempt, never the saved project. Supply only one source selector (preset, template, URL, YouTube or result). Each content image contains exactly one userImageId or url; explicit image URLs must belong to your configured uploaded storage path. Upload external images first. Read jobs[].results[].id from project detail; pass that ID as sourceResultId to iterate on that exact completed image. It must belong to a visible completed job in the same project. A reference selects normal generation; a preset selects magic generation. Deleted projects and results cannot be generated from.

json

{"projectId":"<project-id>","sourceResultId":"<result-image-id>","prompt":"Keep this composition and brighten the background","advancedOptions":{"variations":1}}

POST /api/thumbnails/jobs/:jobId/retry / retry_generation({jobId}) accepts a failed Default job only. It creates a new billed attempt in the same project, preserving the failed prompt, input images, persons, title, preset and options; it never resets the failed job or uses changed project defaults. The new metadata records retryOfJobId. Every call is non-idempotent and consumes generation credits again. Success includes jobId, projectId, status, creditsConsumed only after launch acknowledgement. A synchronous launch failure refunds credits and fails the orphan job.

Prompt assistance

POST /api/thumbnails/prompts/improve / improve_prompt: prompt plus optional context with axes (composition, hook, readability), language (fr, en, es), personName, title, customInstruction, hasStyleReference, referenceTokens (@image1...), sketchTokens (@sketch1...). POST /api/thumbnails/prompts/from-reference / prompt_from_reference: exactly one of assetId, published or own-private templateId, projectId + sourceResultId, or imageUrl proven to be an upload owned by the caller; optional language (default en). Arbitrary URLs are refused; upload first. References are authorized in the selected organization before billing. Both return {prompt, creditsConsumed: 0.5} without creating a project or image. Provider failure refunds once. MCP requires mcp:generate and Generation enabled. Its daily cap counts exact half credits; changing the tool does not evade the limit. Existing integer limits retain their meaning.

Compact exploration and explicit counts

Prefer get_generation({projectId, summary:true, page:1, limit:5}) or GET /api/thumbnails/:projectId?summary=true&page=1&limit=5 for exploration and polling. summary=true defaults to page 1 and limit 20 (1–100); status still accepts comma-separated statuses. The response contains projectId, projectName, status, isFavorite, the full-project summary, pagination, and jobs with only jobId, status, type, isFavorite, userPrompt, generatedFileUrl, createdAt. It omits project/job metadata, embedded images and persons. Full prompts are retained, so there is no fixed byte-size guarantee. Follow pagination.hasMore for further pages. For result image IDs needed by sourceResultId, request a bounded detailed page with summary:false. summary absent or false preserves the existing detailed contract, including unbounded status-only reads. list_generations / GET /api/thumbnails/results now includes the complete userPrompt (or null) per job; no detail call is required to read prompts. get_credits / GET /api/usage adds counts.activeGenerationProjects (non-deleted projects, all generation types) and counts.completedThumbnailJobs (completed, non-deleted jobs in visible thumbnail projects; same scope as unfiltered list_generations). These are organization-scoped counts of projects and jobs, not images or credits consumed. Existing generations statistics still count projects; generations.total equals counts.activeGenerationProjects. Credits and historical counters are unchanged. Project favorites (generation_project), job favorites (generation_job) and personal bucket file favorites are separate. list_thumbnail_projects({favorite:true}) may correctly return zero even with many favorite jobs: it does not select projects merely containing favorite jobs. If tool parameters omit summary, page, limit or asset search, refresh/reconnect the MCP client and reload its tool list; updating the skill alone does not update cached tool schemas.

Base URL

Endpoints Overview

POST /thumbnails

Request Body

Advanced Options

Response 201 Created

POST /thumbnails/:projectId/start

Override Options

Success Response 200 OK

Error Response 402 Payment Required

GET /thumbnails/:projectId/status

Query Parameters

Response (without pagination)

Response (with pagination)

Status Values

GET /thumbnails/:projectId/detailed-status

Detailed Response

Complete Workflow Example

Library, favorites and trash

Attempts, iteration and retry

Prompt assistance

Compact exploration and explicit counts

Response `201 Created`

Success Response `200 OK`

Error Response `402 Payment Required`