Thumbnails

BETA Generate a YouTube thumbnail from a title and one or more reference thumbnails. The reference is vision-analysed and its design grammar is folded into an engineered prompt for your new title, then rendered. Returns a task_id immediately — poll /api/thumbnails/status/{task_id} for the image URLs. Costs 1 credit (or a flat 3 with fast: true), deducted upfront and refunded automatically if generation fails.

BETA Generate a thumbnail in a specific channel's own design style. We resolve the channel, pull its top longform thumbnails, analyse them, pick the one whose design best fits your title, and recreate that treatment for your title (the channel's subjects never carry over — only its design language). Returns a task_id immediately — poll /api/thumbnails/status/{task_id} for the image. Costs 1 credit (or a flat 3 with fast: true), deducted upfront and refunded automatically on failure.

BETA Edit an already-generated thumbnail with a plain-English instruction. The image goes back to the model as the canvas and only the requested change is applied — optional reference_urls are source material for the change ("insert THIS product"). Returns a task_id immediately — poll /api/thumbnails/status/{task_id} for the edited image. Costs 1 credit (or a flat 3 with fast: true), deducted upfront and refunded automatically on failure. Note: gpt-image-2 requests are served by nano-banana-pro for edits.

BETA List the thumbnail models available to your account, their per-generation credit cost, and the fast-mode flat rate. Free — use this for capability discovery instead of hardcoding model names.

BETA Retrieve the status and result of a thumbnail generation. Poll every 2–3 seconds until state is success or fail. Typical generation time is 30–90 seconds. On a failure, the credits charged at submit are refunded automatically.

BETA Find topically-similar, high-performing reference thumbnails for a topic. Free (a database lookup, no credits). Pass the returned thumbnail_url values straight into POST /api/thumbnails as reference_urls to build a thumbnail in a proven style.

BETA Page through a channel's LONGFORM upload catalogue (shorts excluded) — newest first, 50 per page, each video with its thumbnail, title and view count, plus the channel's recent-median baseline (median_views) for outlier scoring (view_count / median_views). Free (1–2 YouTube quota units per page, no credits). Pick a thumbnail_url and pass it to POST /api/thumbnails as a reference.

BETA List your saved channel styles (identity only — name, handle, avatar, channel id). The catalogue itself is always fetched live via POST /api/thumbnails/channel-videos. Free.

BETA Save a channel style for one-click reuse. Snapshots the channel's name, handle and avatar (1 YouTube quota unit). Upserts by channel. Free.

BETA Remove a channel from your saved styles. Free.

BETA List your saved custom-instruction presets. Apply one by passing its instructions as custom_instructions to the compose/generate endpoints. Free.

BETA Save (or update, by name) a reusable custom-instruction preset for thumbnail generation. Free.

BETA Delete a custom-instruction preset by id (from the list endpoint). Free.

BETA Resolve a YouTube URL or video ID to its title, channel, and max-resolution thumbnail. Free (no credits). Use the returned thumbnail_url as a reference for POST /api/thumbnails.

BETA Vision-analyse a thumbnail image into a structured design breakdown (composition, palette, text, focal points). Free (no credits).

BETA Engineer an image-gen prompt from a title + a single reference, without generating. Free, synchronous. Stateless — there is no style id; save the returned prompt and pass it to POST /api/thumbnails as final_prompt to render.

BETA Channel-style compose without generating — resolve the channel, analyse its top thumbnails, match the best design to your title. Free, synchronous (~30–90s). Returns the engineered prompt + the channel's source_thumb_urls; pass both to POST /api/thumbnails (final_prompt + reference_urls) to render. Stateless.

BETA List your saved per-channel thumbnail presets — instructions, subject face, style references, and generation defaults, saved together under a label. Returns the 50 most recent. Free.

BETA Save a per-channel preset, or update an existing one by reusing its label. Only the fields you send are written; on update, everything you leave out keeps its current value. Free.

BETA Delete a per-channel preset by id (from the list endpoint). Free.

BETA Check whether a reference image contains a person, so you can offer to swap in a real face before rendering. Cheaper and faster than a full analysis, and cached per image for six hours. Free.

BETA Crop a region out of a reference image and store it as a character reference. The crop happens server-side, so it works on images a browser canvas is not allowed to read back. Returns a hosted URL you can pass straight to generation as a character reference. Free.

BETA Search the web for photos of a named person so you can use one as a character reference. Pass the chosen photo through /api/thumbnails/import-face before rendering — some image hosts block our downloader. Free.

BETA Copy an external face photo into Algrow storage and return a stable URL the render pipeline can always fetch. Run every search result through this before using it as a reference. Free.

BETA Put a real face onto a thumbnail you already rendered. Queues like any other generation and returns a task_id to poll. Costs 1 credit, or 3 with fast enabled.

BETA Record a thumbs up or down on a generated thumbnail, with an optional comment. Sending the same task_id again updates the existing rating. Free.