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:

usePhoto and useLogo are independent — you can use either, both, or neither on the same request. 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",
  "category": "lifestyle-vlog",
  "usePhoto": true
}

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

Inline Alternative

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

{
  "title": "My Journey to 1M Subscribers",
  "format": "youtube",
  "usePhoto": true,
  "photoImage": "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. Logos are composited onto the final image programmatically — sharp, with the saved position, size, and drop shadow from your dashboard config.

Upload

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

Use in API Calls

{
  "title": "Q1 2026 Product Update",
  "format": "blogpost",
  "category": "business-finance",
  "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

You can send a logo inline via logoImage if you need different logos per request:

{
  "title": "Q1 2026 Product Update",
  "format": "blogpost",
  "useLogo": true,
  "logoImage": "data:image/png;base64,iVBORw0KGgo..."
}

The image must be under 1MB (logos compress well, so this is smaller than the 2MB photo cap).

Photo + Logo Together

usePhoto and useLogo are independent flags, so you can combine them on the same request to get your face in the scene plus your brand logo overlaid in the corner.

{
  "title": "My 2026 Annual Review",
  "format": "youtube",
  "usePhoto": true,
  "useLogo": true
}

You can mix saved + inline freely — e.g. usePhoto: true (saved photo) with useLogo: true and a per-request logoImage.

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 clones your set's style at 80–100% fidelity — 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. Pick the format the set is for (youtube, blogpost, linkedin, instagram, or x)
4. Upload 1–6 reference images — these can be your best existing thumbnails, competitor examples you want to emulate, or custom mockups
5. 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",
  "customAssetsId": "m6XhjtZNdF0N2AFXUOiq"
}

That single parameter is the only change from a standard request. format is optional when customAssetsId is set — the set's stored format wins (and any format you send is ignored).

Combining with Other Assets

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

{
  "title": "Why I Quit My 9-to-5",
  "usePhoto": true,
  "useLogo": true,
  "customAssetsId": "m6XhjtZNdF0N2AFXUOiq"
}

This generates a thumbnail with your face in the scene, your logo in the corner, all 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,
    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.

Legacy Parameter Names

The older imageStyle / personImage / usePersonalPhoto parameters still work for backward compatibility — existing SDKs and the WordPress plugin keep generating without changes:

You cannot combine photo + logo through the legacy imageStyle enum — use the new usePhoto / useLogo flags for that case.

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