Thumbnails

Get current thumbnail generation quota and usage for your team. Returns up to three quota pools: the free pool (included with every plan), an optional add-on pool (monthly subscription), and an optional pack pool (one-time purchased credits). The total_remaining field provides the combined remaining generations across all pools.

Rate limit: 60 requests per minute

{
    "success": true,
    "data": {
        "eligible": true,
        "free_pool": {
            "limit": 5,
            "used": 2,
            "reserved": 1,
            "remaining": 2,
            "next_reset": "2026-04-01"
        },
        "addon_pool": {
            "limit": 50,
            "used": 10,
            "reserved": 0,
            "remaining": 40,
            "next_reset": "2026-04-15"
        },
        "pack_pool": {
            "limit": 100,
            "used": 5,
            "reserved": 0,
            "remaining": 95,
            "next_reset": null
        },
        "total_remaining": 137
    }
}

Create an asynchronous thumbnail generation for a channel. Three main modes: (1) **Idea-based** — provide an idea_id to generate a final 2K thumbnail from an existing idea. (2) **Brainstorm** — provide a prompt (no idea_id) to generate concept sketches at 1K resolution. Brainstorm results are stored as concept variations on a new idea; to produce final 2K thumbnails, call this endpoint again with the returned idea_id. (3) **Clone** — provide a clone_strategy and reference_image_url to generate thumbnails that match an existing thumbnail's style. The generation runs in the background; poll the returned run_id for status or use callback_url for async notification.

Rate limit: 12 requests per minute

{
    "idea_id": 42,
    "num_variations": 3,
    "callback_url": "https://partner.example.com/subscribr/thumbnail-callback",
    "callback_secret": "whsec_thumbnail_partner_secret"
}

{
    "success": true,
    "data": {
        "run_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
        "run_ids": [
            "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
        ],
        "status": "queued"
    }
}

• Clone with style_analysis: When clone_strategy=style_analysis, the response has a different shape: { idea_id, status: "style_analysis_pending", message }. Style analysis runs asynchronously before thumbnail generation. Use a callback_url to be notified when analysis completes, then call this endpoint again with the returned idea_id to generate the final thumbnail.
• Quota consumption: Quota is reserved per generation run. When num_variations > 1 with an idea_id, each variation gets its own run_id and consumes one quota unit. Brainstorm mode (no idea_id) reserves one unit for the batch. Reserved quota is released if a run fails.

Get the current status and results of a thumbnail generation. When the status is "completed", the output_urls array contains URLs to the generated thumbnail images. Poll this endpoint after creating a generation to track progress.

Rate limit: 120 requests per minute

{
    "success": true,
    "data": {
        "run_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
        "status": "completed",
        "idea_id": null,
        "output_urls": [
            "https://subscribr.ai/storage/thumbnails/9b1deb4d_v1.png",
            "https://subscribr.ai/storage/thumbnails/9b1deb4d_v2.png"
        ],
        "created_at": "2026-02-27T10:30:00Z",
        "updated_at": "2026-02-27T10:30:45Z"
    }
}

List past thumbnail generation runs for a channel. Returns a paginated list (15 per page) ordered by most recent first. Optionally filter by source_type to narrow results to a specific generation mode.

Rate limit: 120 requests per minute

{
    "success": true,
    "data": [
        {
            "run_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
            "status": "completed",
            "source_type": "api_generate",
            "idea_id": 42,
            "output_urls": [
                "https://subscribr.ai/storage/thumbnails/9b1deb4d_v1.png"
            ],
            "created_at": "2026-02-27T10:30:00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 3,
        "per_page": 15,
        "total": 42
    }
}

Read the channel's Thumbnail Studio board: a spatial canvas of image tiles (imported thumbnails, uploads, AI variations, exports) and editable text overlays. Each channel has one board. Returns every item with its position, status, and image URL. Items with status "generating" are still rendering — poll this endpoint until they turn "ready". The studio_url field links to the board in the Subscribr app.

Rate limit: 120 requests per minute

{
    "success": true,
    "data": {
        "channel_id": 1,
        "board_id": 12,
        "studio_url": "https://subscribr.ai/channels/1/thumbnails",
        "credits_remaining": 42,
        "items": [
            {
                "id": 311,
                "type": "image",
                "status": "ready",
                "x": 48,
                "y": 128,
                "width": 320,
                "height": 180,
                "frame_id": 310,
                "url": "https://subscribr.ai/storage/thumbnails/boards/311.png",
                "label": "How I fixed my retention",
                "source": "youtube_video"
            }
        ]
    }
}

Import reference images onto the board as a labeled frame. Sources my_recent, my_top_viewed, and my_top_outlier pull the channel's own YouTube thumbnails; source urls adds up to 12 external image URLs, optionally tagged with a usage such as creator_face (exact likeness) or style (visual style to copy). Added images can then be passed as reference_item_ids to Create Board Generation.

Rate limit: 12 requests per minute

{
    "success": true,
    "data": {
        "board_id": 12,
        "items": [
            {
                "id": 311,
                "type": "image",
                "status": "ready",
                "x": 48,
                "y": 128,
                "width": 320,
                "height": 180,
                "frame_id": 310,
                "url": "https://example.com/reference.png",
                "usage": "style",
                "source": "upload"
            }
        ]
    }
}

Render new thumbnail variations onto the board from a prompt plus selected reference items. Spends 1 thumbnail credit per variation. Rendering is asynchronous (typically 10-60 seconds per image): the response returns placeholder items with status "generating" — poll Get Thumbnail Board until they turn "ready". Failed renders release their credit automatically. Text is kept out of the generated image by default; words in the prompt become an editable text overlay instead. Set allow_text to true to bake text into the image.

Rate limit: 12 requests per minute

{
    "success": true,
    "data": {
        "board_id": 12,
        "credits_spent": 2,
        "credits_remaining": 40,
        "items": [
            {
                "id": 312,
                "type": "image",
                "status": "generating",
                "x": 48,
                "y": 360,
                "width": 320,
                "height": 180,
                "prompt": "Shocked face pointing at a giant chart",
                "source": "generation"
            }
        ],
        "note": "Rendering is asynchronous (typically 10-60 seconds per image). Poll GET /thumbnails/board until these items turn \"ready\"."
    }
}

Change one ready board image with a plain-language instruction such as "remove the text" or "make the sky stormy". Spends 1 thumbnail credit. Non-destructive: the edit arrives as a new item beside the original, which is never altered, so you can compare takes and keep the one you want. Pass an optional region to confine the change to a rectangle of the image — pixels outside it are guaranteed identical to the original, because Subscribr composites the model output back over the source rather than trusting the model to stay inside the lines. Rendering is asynchronous (typically 10-60 seconds): poll Get Thumbnail Board until the new item turns "ready". A failed edit releases its credit automatically.

Rate limit: 12 requests per minute

{
    "success": true,
    "data": {
        "board_id": 12,
        "credits_spent": 1,
        "credits_remaining": 39,
        "items": [
            {
                "id": 318,
                "type": "image",
                "status": "generating",
                "x": 392,
                "y": 360,
                "width": 320,
                "height": 180,
                "prompt": "Remove the text",
                "source": "generation"
            }
        ],
        "note": "The edit renders asynchronously as a new item beside the original, which is left unchanged. Poll GET /thumbnails/board until it turns \"ready\"."
    }
}

Add or update an editable headline overlay. Overlay text stays out of the generated image on purpose so it can be edited and swapped freely. Place a new overlay over an image with over_item_id, or pass item_id to update an existing overlay. Styling defaults come from the channel's analyzed thumbnail identity. Use Export Board Image to flatten overlays into a final PNG.

Rate limit: 12 requests per minute

{
    "success": true,
    "data": {
        "board_id": 12,
        "item": {
            "id": 313,
            "type": "text",
            "status": "ready",
            "x": 62,
            "y": 140,
            "width": 292,
            "height": 60,
            "content": "I WAS WRONG",
            "source": "agent"
        }
    }
}

Flatten one ready image with every text overlay that overlaps it into a final 1280x720 PNG. Returns the stored URL and adds the export back onto the board as a new item. This is how an agent produces the finished, downloadable thumbnail.

Rate limit: 12 requests per minute

{
    "success": true,
    "data": {
        "board_id": 12,
        "url": "https://subscribr.ai/storage/thumbnails/boards/export-314.png",
        "item": {
            "id": 314,
            "type": "image",
            "status": "ready",
            "x": 408,
            "y": 128,
            "width": 320,
            "height": 180,
            "url": "https://subscribr.ai/storage/thumbnails/boards/export-314.png",
            "source": "export"
        },
        "overlays_flattened": 1
    }
}

Make a ready board image the thumbnail of a project (script) on this channel. Uses the same exclusive winner semantics as selecting a thumbnail on the Kanban board: the image is stored as a script attachment, marked as the thumbnail winner, and shown on the project card and detail view. The board item is stamped with assigned_script_id and assigned_script_title so later board reads show which image belongs to which project.

Rate limit: 12 requests per minute

{
    "success": true,
    "data": {
        "script_id": 88,
        "attachment_id": 402,
        "thumbnail_url": "https://subscribr.ai/storage/kanban-attachments/402.png"
    }
}