Thumbnail Generation

Default entry point for a brand-new thumbnail. Searches Algrow's database for topically-similar videos with proven outlier performance and renders them as a clickable grid in the thumbnail studio widget. Requires a specific YouTube niche or video title (2+ meaningful words) — generic single words like 'thumbnail' or 'video' are rejected.

Use a specific YouTube video as the reference for a new thumbnail. Pulls the video's title and best-quality thumbnail via youtubei.js and mounts the widget with the reference preselected. If user_title is passed, the widget auto-runs the full pipeline (compose engineered prompt → generate image) with stage-by-stage progress.

Use a direct image URL (not a YouTube video) as the reference for a new thumbnail — R2 mirrors, raw .jpg/.png/.webp URLs, screenshots the user uploaded, etc. Mounts the widget with the reference preselected and, when user_title is provided, auto-runs the full compose + generate pipeline.

Use a whole channel's design system as the reference. Resolves the @handle or UC id via Algrow, fetches the channel's top 10 thumbnails by view count, vision-analyzes them in parallel, and synthesizes a 'channel DNA' (palette, typography, composition, lighting, effects) plus a tailored prompt applying that DNA to the user's title. ~90–120s first time, ~5s on cache hit (30-day cache).

Submit a thumbnail generation request to the configured image backend (Nano Banana Pro, gpt-image-2, or a Seedream variant). Returns immediately with a task_id; the inline widget polls for the result automatically. Default aspect ratio 16:9. Accepts up to 8 reference URLs (YouTube links, bare video IDs, i.ytimg.com URLs, direct image URLs). Costs 1 credit per image regardless of model.

Apply a plain-English edit to an already-generated thumbnail — a surgical img2img pass, not a regeneration. The finished image goes back to the image model as the canvas plus the instruction; everything the instruction doesn't cover stays identical, and the result lands as a NEW version in the widget's version strip (earlier versions are never overwritten). Returns immediately with a task_id; the widget polls check_thumbnail_status. Powers the widget's Edit box, but Claude may also call it directly when the user asks for a specific edit to an existing render — base_image_url must be a real URL from a completed generation, never invented.

Page through a channel's LONGFORM upload catalogue (shorts excluded) — newest first, 50 per page. Each video carries its thumbnail, title, and view count, plus the channel's recent-median view baseline (median_views) so any video scores as view_count / median_views. Use to hand-pick a specific channel thumbnail as a style reference, or to see what performs on a channel. Pass next_page_token AND playlist_id from the previous response for the next page. Free — no credits.

Manage the user's saved channel styles (the bookmarks in the thumbnail studio's Channel Style tab). action='list' returns them; action='save' bookmarks a channel; action='remove' deletes one. Saves store identity only — the catalogue is always fetched live via list_channel_thumbnails, so new uploads always appear. Free.

Manage the user's reusable custom-instruction presets for thumbnail generation (e.g. 'dark moody palette, no extra text'). action='list' returns them; action='save' creates or updates by name; action='remove' deletes by id. Apply a preset by passing its instructions as custom_instructions to compose/generate. Free.

Manage presets for your OWN channels — one saved bundle per channel so you don't re-specify your look every time. Keyed by a free-form label (e.g. 'Marion Vale hair'), a preset bundles custom instructions, a subject face that is auto-added as the on-camera person on every generation, and default model / aspect_ratio / resolution. How it differs: instruction_presets holds only reusable TEXT; saved_channel_styles bookmarks OTHER channels to borrow a look from; this is the full recipe for YOUR channel. action='list' returns them; action='save' creates or updates by label; action='remove' deletes by id. Apply one by passing its label as channel_preset to generate_thumbnail / compose_thumbnail_prompt / extract_reference_from_video / extract_reference_from_image: the face becomes reference 1 (the person), the picked reference supplies the style, and instructions + defaults fold in. Free.

Internal poll for the thumbnail studio widget — looks up the status of a generation task by task_id. The widget calls this on a loop while a generation is in flight; Claude should not normally invoke it from chat.

Check whether a reference image has a person in it, so you can offer to put the user's own face in the render instead of a stranger's. Cheaper and faster than a full thumbnail analysis, and cached per image for six hours. Free — no credits.

Find photos of a person by name so one can be used as an identity reference — either as a character reference when generating, or as the face for swap_face. Returns candidate image URLs; run the chosen one through import_face before rendering with it. Free — no credits.

Copy a face image into Algrow storage and return a stable URL the render pipeline can always fetch. Always run an external face URL through this before using it as a character reference or in swap_face — hotlinked sources can start refusing the download at render time. Free — no credits.

Put a real person's face onto a thumbnail you already generated, leaving everything else in the image untouched. base_image_url must come from a completed generation; face_url is the person's photo (run external URLs through import_face first). Costs 1 credit, or 3 with fast. Returns a pending task_id — the inline widget polls it, so pass wait=true from clients without one.

Record a thumbs up or down on a generated thumbnail, with an optional note. Sending the same task_id again updates the existing rating rather than adding a second one. Free — no credits.