Logo
ThumbnailCreator
Docs
API Endpoints

API Endpoints

Complete reference of all available API endpoints.

API Endpoints

This page provides a quick reference of all available endpoints. For interactive documentation with request/response examples, visit the Swagger UI.

Authentication

MethodEndpointDescription
GET/auth/verifyVerify API key and get organization info

Account

MethodEndpointDescription
GET/account/creditsGet credit balance
GET/account/usageGet usage history

Clips

AI Clips turns long YouTube videos into short-form MP4s for YouTube Shorts, TikTok, and Reels. Analysis is free. Rendering finished clips costs 2 credits per clip.

MethodEndpointDescriptionCredits
GET/clips/projectsList clip projects-
POST/clips/projectsAnalyze a YouTube video and create a clip projectFree
GET/clips/projects/{projectId}Get analyzed clips and source-video readiness-
GET/clips/projects/{projectId}/rendersList render jobs for a project-
POST/clips/projects/{projectId}/rendersRender one or more clips to MP42 per clip
GET/clips/renders/{renderId}Poll a render job status and output URL-

AI Clips Workflow

The clips API is asynchronous:

  1. Create a project with POST /clips/projects
  2. Save clip IDs from data.clips
  3. Poll GET /clips/projects/{projectId} until data.downloadStatus is "ready"
  4. Start renders with POST /clips/projects/{projectId}/renders
  5. Poll GET /clips/renders/{renderId} until data.status is "completed"
  6. Download the finished MP4 from data.outputUrl

Analyze Video for Clips

POST /clips/projects accepts a YouTube URL and returns ranked short-form moments. It also starts preparing the source video in the background.

ParameterTypeRequiredDescription
youtube_urlstringYesFull YouTube video URL
formatstringNo"portrait" for 9:16 output (default) or "landscape" for 16:9 output
{
  "youtube_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "format": "portrait"
}

Response:

{
  "data": {
    "id": "project_uuid",
    "videoTitle": "How I built my channel",
    "downloadStatus": "downloading",
    "format": "portrait",
    "analysis": {
      "contentType": "tutorial",
      "suggestedFormat": "portrait",
      "suggestedStyle": "bold"
    },
    "clips": [
      {
        "id": "clip-1",
        "title": "The moment everything changed",
        "startTime": 42.5,
        "endTime": 78.2,
        "hook": "A strong before-and-after reveal that works as a standalone short.",
        "category": "story",
        "viralScore": 8.7,
        "hookStrength": "strong",
        "platformFit": ["Shorts", "TikTok", "Reels"],
        "mood": "inspiring",
        "keywords": ["changed", "built", "result"]
      }
    ]
  }
}

Get Clip Project

Use GET /clips/projects/{projectId} to poll readiness. Renders require downloadStatus to be "ready"; otherwise the render endpoint returns 409.

{
  "data": {
    "id": "project_uuid",
    "downloadStatus": "ready",
    "clips": []
  }
}

Render Clips

POST /clips/projects/{projectId}/renders accepts one clip ID or up to 10 clip IDs. Failed render jobs are refunded by the render pipeline.

ParameterTypeRequiredDescription
clip_idstringEither/orRender a single clip
clip_idsstring[]Either/orRender multiple clips, up to 10
formatstringNo"portrait" or "landscape"
subtitle_stylestringNo"bold", "clean", "minimal", "energetic", or "glow"
brand_iduuidNoBrand used for brand frame and end-card logo
optionsobjectNoRender customizations

Render options:

OptionTypeDescription
musicbooleanAdd background music when available
musicTrackIdstringUse a specific music track instead of the AI pick
brollbooleanGenerate and insert contextual AI b-roll
hookTitlebooleanAdd an animated hook title intro
progressBarbooleanAdd a short-form progress indicator
brandFramebooleanAdd a brand-colored frame; requires brand_id
endCardTextstringCTA text for the end card, max 120 characters
keywordEmphasisbooleanHighlight important words in captions
{
  "clip_ids": ["clip-1", "clip-2"],
  "format": "portrait",
  "subtitle_style": "bold",
  "options": {
    "music": true,
    "broll": true,
    "hookTitle": true,
    "progressBar": true,
    "keywordEmphasis": true,
    "endCardText": "Follow for more"
  }
}

Response:

{
  "data": {
    "renders": [
      {
        "id": "render_uuid",
        "clipId": "clip-1",
        "status": "pending",
        "creditsCharged": 2
      }
    ],
    "creditsCharged": 4
  }
}

Poll Render Status

GET /clips/renders/{renderId} returns render progress. When status is "completed", use outputUrl to download the MP4.

{
  "data": {
    "id": "render_uuid",
    "projectId": "project_uuid",
    "clipId": "clip-1",
    "status": "completed",
    "progress": 100,
    "currentStep": "finalize",
    "format": "portrait",
    "outputUrl": "https://storage.example.com/clips/render_uuid.mp4",
    "creditsCharged": 2,
    "error": null,
    "createdAt": "2026-06-13T18:30:00.000Z",
    "completedAt": "2026-06-13T18:33:12.000Z"
  }
}

Thumbnails

MethodEndpointDescriptionCredits
GET/thumbnailsList thumbnails-
POST/thumbnailsGenerate a thumbnail1
GET/thumbnails/{id}Get thumbnail details-
DELETE/thumbnails/{id}Delete a thumbnail-
POST/thumbnails/analyzeAnalyze video for concepts-
POST/thumbnails/variationsGenerate variations1 each

Generate Thumbnail Parameters

The POST /thumbnails endpoint accepts these parameters:

ParameterTypeRequiredDescription
promptstringYesThumbnail description/concept
styleIduuidNoStyle to apply
brandIduuidNoBrand for colors
faceIdsuuid[]NoFaces to include
referenceImageUrlsurl[]NoReference images for style guidance (no Style required)
aspectRatiostringNo"16:9" (default) or "9:16"
collectionIduuidNoCollection to add thumbnail to

Analyze Video for Concepts

POST /thumbnails/analyze returns three AI-generated thumbnail concepts (each with a ready-to-use prompt) for a video. Provide either a YouTube URL or a transcript — exactly one is required.

ParameterTypeRequiredDescription
youtubeUrlstringEither/orYouTube URL — we fetch the transcript
transcriptstringEither/orFull transcript (≥50 chars). Use this for unlisted/private videos, podcasts, or any source where the transcript isn't auto-discoverable
videoTitlestringNoTitle used to anchor concepts when sending a transcript. Defaults to "Your Video"

From a YouTube URL:

{
  "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

From a transcript:

{
  "transcript": "In this episode we break down how creators are using AI to generate thumbnails at scale. The first thing we noticed...",
  "videoTitle": "How creators 10x'd CTR with AI thumbnails"
}

Response:

{
  "data": {
    "video": {
      "title": "How creators 10x'd CTR with AI thumbnails",
      "summary": "..."
    },
    "concepts": [
      {
        "id": "concept-1",
        "title": "...",
        "description": "...",
        "prompt": "...",
        "hookText": "...",
        "textStyle": "...",
        "textPlacement": "..."
      }
    ]
  }
}

Pass any concept's prompt straight into POST /thumbnails to generate the image.

Editing

All editing endpoints accept an image URL and return the edited result. Some are free, others cost 1 credit.

MethodEndpointDescriptionCredits
POST/thumbnails/editGeneral AI edit with prompt1
POST/thumbnails/edit/face-swapSwap a face onto an image1
POST/thumbnails/edit/background-removeRemove background (transparent PNG)Free
POST/thumbnails/edit/background-replaceReplace background with new scene1
POST/thumbnails/edit/color-enhanceApply color grading presetFree
POST/thumbnails/edit/upscaleUpscale image 2x or 4xFree
POST/thumbnails/edit/filterApply visual style/filterFree
POST/thumbnails/edit/combineCombine two images into one1

Edit Endpoint Details

General Edit (POST /thumbnails/edit)

{
  "imageUrl": "https://...",
  "prompt": "Change the sky to a sunset",
  "referenceImageUrls": ["https://..."],
  "aspectRatio": "16:9"
}

Face Swap (POST /thumbnails/edit/face-swap)

Provide either faceImageUrl (a direct URL) or faceId (a saved face ID):

{
  "imageUrl": "https://...",
  "faceImageUrl": "https://..."
}

Background Remove (POST /thumbnails/edit/background-remove)

{
  "imageUrl": "https://..."
}

Background Replace (POST /thumbnails/edit/background-replace)

{
  "imageUrl": "https://...",
  "backgroundPrompt": "tropical beach at sunset",
  "aspectRatio": "16:9"
}

Color Enhance (POST /thumbnails/edit/color-enhance)

Presets: vibrant, dramatic, warm, cool, high-contrast, cinematic

{
  "imageUrl": "https://...",
  "preset": "cinematic",
  "intensity": "medium"
}

Upscale (POST /thumbnails/edit/upscale)

{
  "imageUrl": "https://...",
  "scale": "2x"
}

Filter (POST /thumbnails/edit/filter)

{
  "imageUrl": "https://...",
  "filterPrompt": "oil painting style"
}

Combine (POST /thumbnails/edit/combine)

{
  "imageUrl1": "https://...",
  "imageUrl2": "https://...",
  "prompt": "Place the person from image 2 into image 1",
  "aspectRatio": "16:9"
}

Edit Response Format

All editing endpoints return the same structure:

{
  "data": {
    "id": "uuid",
    "imageUrl": "https://...",
    "prompt": "...",
    "creditsCost": 1
  }
}

Utilities

MethodEndpointDescriptionCredits
POST/thumbnails/critiqueAI critique with scores and suggestions1
POST/thumbnails/optimizeOptimize idea into viral thumbnail1
POST/thumbnails/analyze/text-overlayGet text overlay suggestionsFree
POST/thumbnails/extract-youtubeExtract YouTube video thumbnailFree

Utility Endpoint Details

Critique Thumbnail (POST /thumbnails/critique)

Returns scores across 7 dimensions (contrast, composition, text readability, face visibility, color appeal, clickability, emotional impact), strengths, weaknesses, actionable improvements, and an attention heatmap.

{
  "imageUrl": "https://...",
  "niche": "gaming"
}

Response:

{
  "data": {
    "overallScore": 72,
    "scores": {
      "contrast": 8,
      "composition": 7,
      "textReadability": 6,
      "faceVisibility": 9,
      "colorAppeal": 7,
      "clickability": 8,
      "emotionalImpact": 7
    },
    "strengths": ["Strong facial expression", "Good color contrast"],
    "weaknesses": ["Text too small for mobile", "Background too busy"],
    "improvements": ["Increase text size by 30%", "Darken background"],
    "attentionAreas": [
      { "x": 50, "y": 40, "radius": 20, "intensity": 0.9, "label": "Face" }
    ],
    "summary": "Strong emotional impact but text readability needs improvement.",
    "creditsCost": 1
  }
}

Optimize & Generate (POST /thumbnails/optimize)

Takes a rough idea, uses AI to analyze and create a viral-optimized prompt, then generates the thumbnail.

{
  "idea": "a cooking tutorial about making pasta from scratch",
  "collectionId": "uuid"
}

Text Overlay Suggestions (POST /thumbnails/analyze/text-overlay)

Analyzes a thumbnail and suggests what text to add, where to place it, colors, fonts, and styling for maximum CTR.

{
  "imageUrl": "https://...",
  "originalPrompt": "Excited chef in a kitchen",
  "faceName": "Gordon"
}

Extract YouTube Thumbnail (POST /thumbnails/extract-youtube)

Extracts the existing thumbnail from a YouTube video at the highest available quality (maxres > high > medium > standard).

{
  "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

Faces

MethodEndpointDescription
GET/facesList faces
POST/facesCreate a face
GET/faces/{id}Get face details
PATCH/faces/{id}Update a face
DELETE/faces/{id}Delete a face
POST/faces/upload-urlsGet presigned upload URLs

Styles

MethodEndpointDescription
GET/stylesList styles
POST/stylesCreate a style
GET/styles/{id}Get style details
PATCH/styles/{id}Update a style
DELETE/styles/{id}Delete a style

Brands

MethodEndpointDescription
GET/brandsList brands
POST/brandsCreate a brand
GET/brands/{id}Get brand details
PATCH/brands/{id}Update a brand
DELETE/brands/{id}Delete a brand

Collections

MethodEndpointDescription
GET/collectionsList collections
POST/collectionsCreate a collection
GET/collections/{id}Get collection with thumbnails
PATCH/collections/{id}Update a collection
DELETE/collections/{id}Delete a collection
POST/collections/{id}/thumbnailsAdd thumbnail to collection
DELETE/collections/{id}/thumbnailsRemove thumbnail from collection

SEO

MethodEndpointDescription
POST/seo/titlesGenerate video titles
POST/seo/descriptionGenerate video description

Templates

MethodEndpointDescriptionCredits
GET/templatesList templates-
POST/templates/{id}/remixRemix a template1

Uploads

MethodEndpointDescription
POST/uploads/presigned-urlGet presigned upload URL

Common Parameters

Pagination

All list endpoints support pagination:

  • page - Page number (default: 1)
  • limit - Items per page (default: 20, max: 100)

Response Format

All responses follow this structure:

Success:

{
  "data": { ... }
}

Paginated:

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "hasMore": true
  }
}

Error:

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": { ... }
}

HTTP Status Codes

CodeMeaning
200Success
201Created
400Bad Request - Invalid input
401Unauthorized - Invalid API key
402Payment Required - Insufficient credits
403Forbidden - Quota exceeded
404Not Found
429Too Many Requests - Rate limited
500Internal Server Error
QuickstartError Handling