Custom Assets

ThumbAPI lets you save assets once and reuse them across every API call. Instead of encoding and sending an image with each request, upload it to the dashboard and reference it with a single parameter.

There are three types of assets:

All assets are managed in the ThumbAPI dashboard under Assets.

Personal Photo

Use this when you want your face in thumbnails but don't want to send a base64 image on every request.

Upload

1. Go to app.thumbapi.dev → Assets → Personal Photo
2. Upload a clear, well-lit headshot (JPEG or PNG, max 2MB)
3. Save

Use in API Calls

{
  "title": "My Journey to 1M Subscribers",
  "format": "youtube",
  "imageStyle": "with-image",
  "usePersonalPhoto": true
}

The API pulls your saved photo automatically. No need to encode or send the image — just set usePersonalPhoto: true.

Inline Alternative

If you'd rather send the photo directly (e.g., for different photos per request), use personImage instead:

{
  "title": "My Journey to 1M Subscribers",
  "format": "youtube",
  "imageStyle": "with-image",
  "personImage": "data:image/jpeg;base64,/9j/4AAQ..."
}

The image must be under 2MB. JPEG, PNG, and WebP are supported.

Logo

For businesses and branded channels that want their logo in every thumbnail.

Upload

1. Go to app.thumbapi.dev → Assets → Logo
2. Upload your logo (PNG with transparency works best, max 2MB)
3. Save

Use in API Calls

{
  "title": "Q1 2026 Product Update",
  "format": "blogpost",
  "imageStyle": "with-logo",
  "useLogo": true
}

The API composites your logo into the thumbnail design. This is ideal for:

• Company blog OG images
• Branded social media cards
• Product launch thumbnails
• Newsletter header images

Inline Alternative

Same as personal photos — you can send a logo inline via personImage if you need different logos per request:

{
  "title": "Q1 2026 Product Update",
  "format": "blogpost",
  "imageStyle": "with-logo",
  "personImage": "data:image/png;base64,iVBORw0KGgo..."
}

Reference Dataset

A reference dataset is a collection of 1–6 images that define a visual style. When you include a dataset ID in your request, the AI uses those images as style inspiration — matching color palette, visual tone, typography weight, and layout energy to your references.

This is different from a template. A template forces a fixed layout. A dataset guides style while still generating a unique composition for each title.

When to Use a Dataset

• You have 5+ published videos and want to keep a consistent thumbnail look
• You're onboarding a new channel to automation and want to match an existing visual style
• You manage multiple channels that each need a distinct identity
• You're a business generating OG images and want them to match your brand guidelines

Upload

1. Go to app.thumbapi.dev → Assets → Reference Sets
2. Create a new dataset and name it (e.g., "Finance Channel — Clean Dark Style")
3. Upload 1–6 reference images — these can be your best existing thumbnails, competitor examples you want to emulate, or custom mockups
4. Save — you'll get a dataset ID like m6XhjtZNdF0N2AFXUOiq

Tips for good references:

• Quality over quantity — 3 well-chosen images beat 6 inconsistent ones
• Pick images that share a similar color palette, contrast level, and typography weight
• Include the kind of compositions you want (centered text, split layouts, etc.)

Use in API Calls

{
  "title": "How the Roman Empire Actually Collapsed",
  "format": "youtube",
  "imageStyle": "faceless",
  "customAssetsId": "m6XhjtZNdF0N2AFXUOiq"
}

That single parameter is the only change from a standard request. Every thumbnail generated with this ID will follow the visual direction of your references.

Combining with Other Assets

You can use a dataset together with a personal photo or logo:

{
  "title": "Why I Quit My 9-to-5",
  "format": "youtube",
  "imageStyle": "with-image",
  "usePersonalPhoto": true,
  "customAssetsId": "m6XhjtZNdF0N2AFXUOiq"
}

This generates a thumbnail with your face, styled to match your reference dataset.

Managing Multiple Datasets

Create a separate dataset for each channel, brand, or visual direction. Store the IDs in your application config and pass the right one per request:

const CHANNELS = {
  history: "m6XhjtZNdF0N2AFXUOiq",
  finance: "pQ9RksTmBv3X7YZWLNcj",
  trueCrime: "hN2VwxDkGe5A8CUJMPqr",
};

const res = await fetch("https://api.thumbapi.dev/v1/generate", {
  method: "POST",
  headers: {
    "x-api-key": process.env.THUMBAPI_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: videoTitle,
    format: "youtube",
    imageStyle: "faceless",
    customAssetsId: CHANNELS[channelName],
  }),
});

Updating a Dataset

If you rebrand or change visual direction, upload new reference images and replace the dataset. Old thumbnails keep their original style. New ones follow the updated direction — no regeneration needed.

Error Handling

Next Steps

• POST /v1/generate reference — full parameter list
• Code examples — copy-paste snippets in cURL, JS, Python
• Custom asset datasets blog post — in-depth guide with batch processing examples