Thumbnail Generator API

REST API reference for the Thumbnail Generator. For the product overview and UI walkthrough, see Thumbnail Generator.

The Thumbnail Generator is available via the Flokan public API, so you can trigger generations from your own scripts, n8n flows, or any HTTP client.

Authentication

All requests require a workspace API key minted in Workspace Settings → API Keys. Pass the key in the Authorization header:

Authorization: Bearer flk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The key must include the thumbnail_generator scope, and the user who created the key must have the Access Thumbnail Generator permission in the workspace.

Base URL

https://app.flokan.com/api/v1/thumbnail-generator

Endpoints

`POST /generate` — Generate thumbnails synchronously

Generates 1–4 thumbnails and returns the completed record after generation finishes (typically 10–30 seconds).

Request body

Field	Type	Required	Notes
`video_title`	string	yes	1–500 characters
`prompt`	string	conditional	1–10000 characters. Optional when at least one of `youtube_references` or `reference_image_url` is provided.
`image_model`	string	yes	`pro`, `standard`, or `creative`
`aspect_ratio`	string	yes	`16:9`, `4:3`, or `1:1`
`image_count`	integer	yes	1–4
`style_id`	uuid	no	Optional thumbnail style preset
`card_id`	uuid	no	Link the generation to a board card in the workspace
`youtube_references`	string[]	no	Up to 6 thumbnail image URLs (typically the `thumbnail_url` values returned by `/youtube-search`). Server fetches each. The first becomes the primary content reference unless `reference_image_url` is also set.
`reference_image_url`	string	no	A single HTTPS URL pointing to an image you host. Server fetches it and uses it as the primary content reference, taking precedence over `youtube_references[0]`.
`provider`	string	no	Routes the call. Default `"platform"` (Flokan system keys, deducts credits). Set to `"openai"`, `"google"`, `"fal"`, or `"kie"` to use the workspace's configured BYOK key for that provider — no credits are deducted. Strict: errors `422` if the workspace doesn't have that BYOK provider configured + enabled, or if the workspace's plan doesn't include BYOK.

The response includes provider_used (e.g. "system", "google") and credits_consumed (0 when BYOK was used) so you can confirm which path executed.

Response 201

{
  "success": true,
  "data": {
    "id": "f24a8c52-...",
    "workspace_id": "...",
    "card_id": null,
    "video_title": "10 Hidden Hiking Trails",
    "prompt": "Bold red text 'TOP 10' over surprised hiker, mountain backdrop",
    "image_model": "pro",
    "aspect_ratio": "16:9",
    "image_count": 2,
    "status": "completed",
    "image_paths": [
      "WORKSPACE_ID/styles/GENERATION_ID/1.png",
      "WORKSPACE_ID/styles/GENERATION_ID/2.png"
    ],
    "image_urls": [
      "https://images.flokan.com/WORKSPACE_ID/styles/GENERATION_ID/1.png",
      "https://images.flokan.com/WORKSPACE_ID/styles/GENERATION_ID/2.png"
    ],
    "total_file_size_bytes": 2841291,
    "generation_time_ms": 18432,
    "created_at": "2026-05-04T11:00:00.000Z",
    "provider_used": "system",
    "credits_consumed": 12
  }
}

`POST /youtube-search` — Find reference thumbnails

Search YouTube for videos matching a query and return their thumbnail URLs. The returned thumbnail_url values can be passed straight to POST /generate via the youtube_references field — you don't need a YouTube API key of your own.

Request body

Field	Type	Required	Notes
`query`	string	yes	1–200 characters
`page_token`	string	no	Pass the `next_page_token` from a previous response to fetch the next page

Response 200

{
  "success": true,
  "data": {
    "results": [
      {
        "video_id": "dQw4w9WgXcQ",
        "title": "Example Video Title",
        "channel_name": "Example Channel",
        "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
        "view_count": "1623847391"
      }
    ],
    "next_page_token": "CAUQAA"
  }
}

`GET /generations` — List generations

Query params

Param	Type	Notes
`page`	integer	Default `1`
`per_page`	integer	Default `25`, max `100`
`status`	string	`pending`, `generating`, `completed`, `failed`, `timed_out`
`card_id`	uuid	Filter to one card

`GET /generations/:generationId` — Fetch one generation

Returns the same shape as POST /generate's response data.

`DELETE /generations/:generationId` — Delete a generation

Deletes the generation row and removes the underlying images from storage.

{ "success": true, "data": { "id": "...", "deleted": true } }

Errors

All error responses use the envelope { "success": false, "error": "..." }. Common status codes:

Code	Meaning
`400`	Validation error (bad model, ratio, count out of range, …)
`401`	Missing or invalid API key
`402`	Insufficient AI credits or storage limit exceeded
`403`	Missing scope, missing permission, or feature not enabled on the workspace plan
`404`	Generation or card not found in this workspace
`429`	Rate limit exceeded — see `Retry-After` header and `X-RateLimit-*` headers
`500`	Unexpected server or provider error

Rate limits

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. The per-minute limit is determined by the workspace's billing plan.

Cards API Image Editor API

Thumbnail Generator API

Authentication

Base URL

Endpoints

POST /generate — Generate thumbnails synchronously

POST /youtube-search — Find reference thumbnails

GET /generations — List generations

GET /generations/:generationId — Fetch one generation

DELETE /generations/:generationId — Delete a generation