--- title: "Thumbnail Lab" description: "Create and refine YouTube thumbnails without leaving the conversation. Give your AI assistant a video title plus 1–3 reference thumbnails whose style you want to match, get a finished thumbnail back in chat, then keep editing it in plain language — \"make the text yellow\", \"swap the background for a city at night\"." source: "https://dashboard.nexlev.io/docs/mcp/thumbnail-lab" --- # Thumbnail Lab Create and refine YouTube thumbnails without leaving the conversation. Give your AI assistant a video title plus 1–3 reference thumbnails whose style you want to match, get a finished thumbnail back in chat, then keep editing it in plain language — _"make the text yellow"_, _"swap the background for a city at night"_. These are the **same generations and edits** as the Thumbnail Lab in your NexLev dashboard — same account, same allowance, and everything you make in chat shows up in your Lab history. ## Prerequisites - **Connected AI assistant** — Claude, ChatGPT, or any other supported platform - **Signed in with your NexLev account (OAuth)** — [Connect to your AI assistant](/docs/mcp/quickstart) - **Lite, Pro, or Premium plan** — Free plans do not have access. [Upgrade your plan](?required_nexlev_lite_pro_access=true) to get started. > **Warning** > > **OAuth login required.** Thumbnail Lab tools act on your personal Lab > workspace, allowance, and billing, so they are **not available on API-key > connections**. Connect via OAuth to use them. > **Info** > > Your AI assistant calls these tools automatically. Just describe the thumbnail > you want in plain language — it handles references, polling, and edits for > you. ## How It Works ### Generate Give your assistant the **video title** and **1–3 reference thumbnails** whose style you like. It can pull references automatically from NexLev's research tools — for example the thumbnails of outlier videos in your niche via [Trending Videos](/docs/mcp/trending-videos) or [YouTube Tools](/docs/mcp/youtube-tools). Optionally add creative direction (_"use a red arrow"_, _"dark background"_), a short script summary for extra context, or ask for a **text-free** image. ### Wait a moment Generation returns a `jobId` immediately and your assistant polls it for you — jobs typically finish in **30–90 seconds**. The finished thumbnail is shown right in the chat (in ChatGPT it appears in an interactive preview with Copy URL / Download buttons). ### Refine Ask for changes in plain language. Each edit returns a **new version**, and you can keep editing the same thumbnail round after round. You can also edit any past generation, or any image by URL. ## Tools ### Generate #### `generate_thumbnail` Generates a brand-new thumbnail from your video title plus 1–3 reference thumbnails whose style should be matched. Returns a `jobId` immediately — your assistant then polls [`get_thumbnail_generation_status`](#generation-status) until the image is ready. **Best for:** - "Make me a thumbnail for this video title" - "Match the style of the top videos in my niche" - "Give me a textless thumbnail I can add my own copy to" - "Try the same title in a darker, higher-contrast style" **Example prompts:** ``` Generate a thumbnail for my video "I Tried Waking Up at 4AM for 30 Days" — match the style of the top productivity channels ``` ``` Find the 3 highest-outlier videos in the personal finance niche and use their thumbnails as style references for my video "I Saved $10,000 in 90 Days" ``` ``` Generate a thumbnail for "The Truth About AI Coding Tools" using a dark background and a red arrow, based on this reference: https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg ``` ``` Generate a no-text thumbnail for my video "5 Hidden Gems in Japan" so I can add my own headline later ``` ``` Use the pro model to generate a thumbnail for "My $50,000 Home Studio Tour" ``` **Parameters:** | Parameter | Type | Description | | -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `newVideoTitle` | string | **Required.** Title of the video the thumbnail is for | | `referenceThumbnailURLs` | string[] | **Required.** 1–3 HTTPS URLs of reference thumbnails (JPEG/PNG/WEBP/GIF, max 2 MB each) | | `referenceThumbnailTitles` | string[] | Video titles of the references, in the same order — optional, but improves results | | `generationInstructions` | string | Creative direction, e.g. `"use a red arrow"`, `"dark background"` (max 2000 chars) | | `newVideoScript` | string | Script or summary of the video for extra context | | `generationMode` | enum | `classic` (full AI thumbnail with text, default) or `no_text` (textless image) | | `imageModel` | enum | `pro` (highest quality, Pro plan only), `lite` (fast), `gpt-image-2` (OpenAI, Pro plan only) or `gpt-image-2-low` (OpenAI budget tier, all plans). The GPT models are generation-only. Defaults to the best model your plan allows | | `aspectRatio` | enum | `16:9` (default, YouTube), `9:16` (Shorts/Reels/TikTok), `1:1` (square) or `4:5` (portrait) | | `outputResolution` | enum | `1K` (default), `2K` or `4K`. The `lite` model supports `1K` only; higher tiers carry a pay-as-you-go surcharge | > **Tip** > > **Reference thumbnails drive the style.** YouTube thumbnail URLs follow the > pattern `https://i.ytimg.com/vi//maxresdefault.jpg`, so you can point > your assistant at any video — or better, ask it to find outlier videos in your > niche first and reuse their thumbnails as references. Passing > `referenceThumbnailTitles` alongside them helps the model understand what each > reference was selling. ### Generation Status #### `get_thumbnail_generation_status` Checks a generation job and returns the finished image. Your assistant polls this every 5 seconds until the job reports `completed` or `failed`. **What it returns:** - `status` — `pending`, `processing`, `completed`, or `failed` - `imageUrl` — the finished thumbnail, displayed inline in the chat - `generationId` — pass this to [`edit_thumbnail`](#edit-thumbnail) to refine the result **Example prompts:** ``` Is my thumbnail ready yet? ``` ``` Check the status of that generation and show me the image ``` > **Note** > > You rarely need to ask for this — your assistant polls automatically after > calling `generate_thumbnail`. Jobs usually finish within **30–90 seconds**; > polling continues for up to 5 minutes before giving up. **Parameters:** | Parameter | Type | Description | | --------- | ------ | --------------------------------------------------- | | `jobId` | string | **Required.** The `jobId` from `generate_thumbnail` | ### Edit #### `edit_thumbnail` Applies an AI edit to a thumbnail — change text, colors, background, or objects — from a plain-language instruction. Returns a `jobId`; your assistant then polls [`get_thumbnail_edit_status`](#edit-status). Pass the edit prompt plus **exactly one** image source: | Source | When to use it | | -------------- | ---------------------------------------------------------------------------------- | | `documentId` | Continue refining the same Lab document — **preferred for follow-up edits** | | `generationId` | Edit a completed `generate_thumbnail` result (a Lab document is opened for it) | | `imageUrl` | Edit any image by HTTPS URL (JPEG/PNG/WEBP/GIF, max 10 MB — imported into the Lab) | **Example prompts:** ``` Make the text bigger and change it to orange ``` ``` Replace the background with a city at night and keep the person as-is ``` ``` Remove the arrow, then brighten the whole image ``` ``` Edit this thumbnail so the headline reads "90 DAYS LATER": https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg ``` ``` Show me my recent Lab generations and let's edit the second one — make the colors more saturated ``` **Parameters:** | Parameter | Type | Description | | -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `prompt` | string | **Required.** Edit instruction, e.g. `"make the text yellow"` (max 2000 chars) | | `documentId` | string | Lab document to keep refining — from a previous edit | | `generationId` | string | A completed generation to edit — from `get_thumbnail_generation_status` or `list_thumbnail_generations` | | `imageUrl` | string | Arbitrary image to edit by HTTPS URL | | `imageModel` | enum | `pro` (Pro plan only) or `lite`. The GPT models are generation-only and rejected here. Defaults to the best model your plan allows | > **Warning** > > **AI edits apply to the base image.** Manual layers you added in the web > editor stay on top of the thumbnail in the Lab, but they are **not part of the > image returned in chat**. > **Tip** > > **Chain your edits.** Each completed edit returns a `documentId` — reusing it > keeps every round of changes on the same thumbnail instead of starting over. > Your assistant does this automatically when you say "now also…". ### Edit Status #### `get_thumbnail_edit_status` Checks an edit job and returns the edited image. Polled every 5 seconds until `completed` or `failed`. **What it returns:** - `status` — `pending`, `processing`, `completed`, or `failed` - `imageUrl` — the edited thumbnail, displayed inline in the chat - `documentId` — pass it back to [`edit_thumbnail`](#edit-thumbnail) to keep refining the same thumbnail **Example prompt:** ``` Is that edit done? Show me the new version ``` **Parameters:** | Parameter | Type | Description | | --------- | ------ | ----------------------------------------------- | | `jobId` | string | **Required.** The `jobId` from `edit_thumbnail` | ### My Generations #### `list_thumbnail_generations` Lists your past Thumbnail Lab generations, newest first, with their status, image URL, and `generationId` — so you can revisit an earlier thumbnail or pick one up for editing. **Best for:** - "Show me the thumbnails I made this week" - "Find the one I generated for my morning routine video and edit it" **Example prompts:** ``` Show me my last 10 Thumbnail Lab generations ``` ``` List my recent generations and edit the newest one — make the text yellow ``` ``` Show me page 2 of my thumbnail history ``` **Parameters:** | Parameter | Type | Description | | --------- | ------ | ------------------------------------- | | `limit` | number | Results per page — 1–50, default 10 | | `page` | number | Page number, default 1 (newest first) | ## Image Models | Model | Description | Available on | | ------ | --------------- | ------------- | | `pro` | Highest quality | Pro plan | | `lite` | Fast | All Lab plans | If you don't pick a model, you automatically get the best one your plan allows. ## Example Workflows ### Niche-matched thumbnail from scratch ``` Find the 3 highest-outlier videos in the "AI tools" niche from the last 30 days, then generate a thumbnail for my video "I Replaced My Whole Workflow With AI" in their style ``` Your assistant finds the outlier videos, reuses their thumbnails as references, generates, polls, and shows you the result. ### Iterate to a final cut ``` Generate a thumbnail for "The Only Budget Video You Need" based on these two references, then make the text yellow, then swap the background for a plain dark gradient ``` Each round is a separate edit on the same Lab document — you keep every intermediate version. ### Rework an existing thumbnail ``` Take the thumbnail from this video and change the headline to "IT GOT WORSE": https://www.youtube.com/watch?v=dQw4w9WgXcQ ``` ### A/B variants for one title ``` Generate two thumbnails for "I Quit My Job After 9 Years" — one with a dark high-contrast style and one bright and colorful ``` ## Included Allowance One shared allowance across chat and the dashboard — a generation from your AI assistant counts exactly the same as one made in the web Lab. | Plan | Generations | AI edits | | ---- | -------------------- | -------------------- | | Free | — (not available) | — (not available) | | Lite | 3 / day · 10 / month | 3 / day · 15 / month | | Pro | 5 / day · 25 / month | 5 / day · 25 / month | > **Note** > > Thumbnail Lab is available on **Lite, Pro, and Premium** plans only — Free > plan users do not have access. ## Beyond Your Allowance (pay as you go) With **usage credits** enabled in your NexLev account you can keep working after your included allowance runs out — and on non-PRO plans, the pro-tier models (`pro`, `gpt-image-2`) are billed entirely from credits without touching your included allowance. Base rates (1K output; 2K/4K generations add a small surcharge): | Action | Lite model | Pro model | GPT Image 2 | GPT Image 2 Low | | ---------- | ---------- | --------- | ----------- | --------------- | | Generation | $0.09 | $0.16 | $0.12 | $0.07 | | AI edit | $0.07 | $0.14 | — | — | - You're always **told the price before** an over-allowance action is charged. - **Failed jobs are refunded automatically** — you only pay for thumbnails that actually complete. - Pay-as-you-go usage is capped at **30 generations and 30 edits per rolling hour**. Without usage credits enabled, the tools simply stop at your included allowance and tell you when it resets. ## Troubleshooting **"This tool requires an OAuth connection"** - Thumbnail Lab is unavailable on API-key connections. Reconnect your assistant with a NexLev account sign-in — see the [Quickstart](/docs/mcp/quickstart). **Reference thumbnail rejected** - References must be HTTPS URLs pointing at a JPEG, PNG, WEBP, or GIF **under 2 MB**. If a `maxresdefault.jpg` URL 404s, that video has no max-res thumbnail — try `hqdefault.jpg` instead. - You need at least 1 and at most 3 references. **Job stuck on `processing`** - Generations and edits normally finish in 30–90 seconds. Your assistant polls for up to 5 minutes; if it times out, ask it to check the status again with the same `jobId`. **Job failed** - Failed jobs are refunded automatically — no allowance or credits are consumed. Try again, and simplify very long `generationInstructions` if it keeps failing. **`pro` model rejected** - The `pro` and `gpt-image-2` models are Pro-plan only (`gpt-image-2-low` is open to every plan). Omit `imageModel` and you'll get the best model your plan allows. The GPT models can generate but not edit. **Edited image is missing my manual layers** - Expected. AI edits act on the base image; layers you added in the web editor are preserved in the Lab but not baked into the image returned in chat. **Allowance reached** - Enable **usage credits** in your NexLev account to keep going past your included allowance, or wait for the reset your assistant reports. [Upgrade to Pro](?required_nexlev_lite_pro_access=true) for a larger included allowance. ## What's Next? - **[Trending Videos](/docs/mcp/trending-videos)** — Find the outlier videos whose thumbnails make the best style references - **[Similar Thumbnails](/docs/mcp/similar-thumbnails)** — Search thumbnails visually across millions of YouTube videos - **[Swipefile](/docs/mcp/swipefile)** — Save the thumbnails and videos you want to model - **[Channel Analytics](/docs/mcp/channel-analytics)** — Study the channels behind the styles you're matching - **[Niche Overview](/docs/mcp/niche-overview)** — Understand the audience you're designing for