Thumbnails

GET

/team/thumbnails/usage

Required Permission scripts:read thumbnails:read

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.

Request

Response (200)

Response Fields

Field	Type	Description
data.eligible	boolean	Whether the team is eligible for thumbnail generation (requires active subscription)
data.free_pool	object	Free pool included with every plan
data.free_pool.limit	integer	Monthly free generation limit
data.free_pool.used	integer	Completed generations this period
data.free_pool.reserved	integer	In-progress generations (counted against remaining until completed or released)
data.free_pool.remaining	integer	Available generations (limit minus used minus reserved)
data.free_pool.next_reset	string\|null	Pool reset date (Y-m-d format)
data.addon_pool	object\|null	Monthly add-on subscription pool (null if not subscribed). Same fields as free_pool.
data.pack_pool	object\|null	One-time purchased credit pack (null if none purchased). Same fields as free_pool. next_reset is always null — pack credits do not expire.
data.total_remaining	integer	Combined remaining across all active pools

Response Example

{
    "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
    }
}

POST

/channels/{id}/thumbnails/generations

Required Permission scripts:write thumbnails:write

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.

Request

Parameters

Name	Type	Description
id	integer	Channel ID (path parameter).

Request Body

{
    "idea_id": "integer (optional) \u2014 Generate thumbnail from an existing idea. Required for improvement_mode.",
    "prompt": "string (required if no idea_id, clone_strategy, or improvement_mode, max 2000) \u2014 Custom prompt or video title for generation",
    "topic": "string (optional, max 1000) \u2014 Additional topic context for brainstorm mode; improves concept quality",
    "num_variations": "integer (optional, 1-8) \u2014 Number of variations to generate. Default: 4 for brainstorm, 1 for idea-based.",
    "callback_url": "string (optional, HTTPS URL, max 2048) \u2014 Webhook URL for async completion notification",
    "callback_secret": "string (optional, max 255) \u2014 Secret used to sign callback payloads via X-Subscribr-Signature header",
    "improvement_mode": "boolean (optional) \u2014 When true, iterates on an existing idea using feedback. Requires idea_id.",
    "feedback": "string (required if improvement_mode=true, max 5000) \u2014 Feedback describing desired changes to the thumbnail",
    "reference_variation_url": "url (required if improvement_mode=true) \u2014 HTTPS URL of the variation to improve upon",
    "clone_strategy": "string (optional) \u2014 Clone an existing thumbnail style. Values: direct_reference (immediate generation) or style_analysis (two-step: analyze first, then generate)",
    "reference_image_url": "url (required if clone_strategy is set) \u2014 HTTPS URL of the reference thumbnail image to clone"
}

Response (202)

Response Fields

Field	Type	Description
data.run_id	string	Primary generation run ID (UUID). Use this to poll status via the Get Generation Status endpoint.
data.run_ids	array	All run IDs for this request. When num_variations > 1 with an idea_id, each variation gets its own run ID that can be polled individually.
data.status	string	Initial status (always "queued")
data.idea_id	integer	Returned only for clone modes — the auto-created idea ID

Response Example

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

GET

/channels/{id}/thumbnails/generations/{runId}

Required Permission scripts:read thumbnails:read

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.

Request

Parameters

Name	Type	Description
id	integer	Channel ID (path parameter).
runId	string	Generation run ID returned from the Create endpoint (path parameter).

Response (200)

Response Fields

Field	Type	Description
data.run_id	string	Generation run identifier (UUID)
data.status	string	Status: queued (processing), completed (output ready), or failed
data.idea_id	integer\|null	Linked idea ID (present when using idea-based or clone modes)
data.output_urls	array	Generated thumbnail image URLs (populated when status is "completed", empty otherwise)
data.output_urls[]	string	URL to a generated thumbnail image
data.created_at	string	ISO 8601 creation timestamp
data.updated_at	string	ISO 8601 last update timestamp (indicates when status last changed)

Response Example

{
    "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"
    }
}

GET

/channels/{id}/thumbnails/generations

Required Permission scripts:read thumbnails:read

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.

Request

Parameters

Name	Type	Description
id	integer	Channel ID (path parameter).
source_type	string	Filter by generation mode: api_generate, idea_improve, thumbnail_brainstorm, thumbnail_clone
page	integer	Page number (default 1).

Response (200)

Response Fields

Field	Type	Description
data[]	array	List of generation run objects
data[].run_id	string	Run identifier (UUID) — use with the Get Generation Status endpoint
data[].status	string	Status: queued, completed, or failed
data[].source_type	string	How the generation was triggered (api_generate, idea_improve, thumbnail_brainstorm, thumbnail_clone)
data[].idea_id	integer\|null	Linked idea ID (null for brainstorm runs without a pre-existing idea)
data[].output_urls	array	Generated thumbnail URLs (empty for queued/failed runs)
data[].created_at	string	ISO 8601 creation timestamp
meta.current_page	integer	Current page number
meta.last_page	integer	Total number of pages
meta.per_page	integer	Items per page (15)
meta.total	integer	Total matching generation runs

Response Example

{
    "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
    }
}