# AI Thumbnail Generator (`dami_studio/viral-thumbnail-generator`) Actor Turn any title or story into a scroll-stopping thumbnail: an AI emotional close-up face with a bold burned-in hook headline. Auto-detects emotion and writes the hook, or set your own. 9:16/16:9/1:1. For YouTube, Shorts, TikTok/Reels covers, ads, course covers, blog headers — any content. - **URL**: https://apify.com/dami\_studio/viral-thumbnail-generator.md - **Developed by:** [Dami's Studio](https://apify.com/dami_studio) (community) - **Categories:** For creators, Marketing, AI - **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $150.00 / 1,000 thumbnail generateds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## AI Thumbnail Generator Turn a title or a story into a thumbnail people actually click: an AI-generated emotional close-up face with a bold hook headline burned across the lower third. Built for YouTube, Shorts and Reels covers, TikTok, and ad creative, where the thumbnail does most of the work and you need a new one for every video. ### How it works It scans your title and story for emotional cues (betrayal, rage, shock, heartbreak, and a few others), picks the strongest match, and writes a short all-caps hook from the same text. That feeds a prompt to gpt-image-1, which renders a hyper-realistic face with deliberately empty space at the bottom. The image comes back text-free on purpose, then the hook is overlaid afterward with a real font so the type stays crisp instead of being mangled by the image model. ### Input You can run it with nothing but a title. Everything else is an override or a knob. | Field | Required | Notes | |---|---|---| | `title` | No* | The video title or story headline. Drives both the detected emotion and the hook. AITA/TIFU shorthand gets expanded automatically. | | `story` | No* | Full script or story text. Gives the emotion detection and hook extraction more to work with. | | `aspectRatio` | No | `9:16` (Shorts/Reels/TikTok, default), `16:9` (YouTube long-form), or `1:1` (square). | | `emotion` | No | Force the facial emotion instead of auto-detecting. One of betrayal, rage, shock, disgust, heartbreak, fear, guilt, defiance. | | `hookText` | No | Force the burned-in headline. Leave empty to derive it from the title or story. | | `gender` | No | Bias the face, e.g. `feminine` or `masculine`. Empty uses the model default. | | `burnText` | No | Overlay the hook on the image. Default true. Turn off to get the raw face only. | | `openaiApiKey` | No | Your OpenAI key for gpt-image-1. Bring your own. Marked secret. | | `imageQuality` | No | gpt-image-1 quality: low, medium, or high. Default high. This is what moves your OpenAI bill. | *At least one of `title` or `story` is needed, otherwise there's nothing to work from. ### Output One PNG per run, saved to the key-value store, with a record pushed to the dataset. The record includes `output.imageUrl` and `output.imageKey` for the file, plus `emotion`, `hookText`, `aspectRatio`, and `size` so you can see what it decided. If the text overlay fails for any reason, you still get the face image back without the headline rather than an error. ### Example ```json { "title": "AITA for refusing to pay for my sister's wedding?", "aspectRatio": "9:16", "imageQuality": "high", "openaiApiKey": "sk-..." } ```` ### Pricing $0.15 per thumbnail, pay per result, no subscription. The image generation runs on your own OpenAI key, so that usage is billed to you separately by OpenAI. ### Notes It needs an OpenAI key with gpt-image-1 access. Emotion detection is keyword-based, so it lands well on emotionally loaded story titles (relationship drama, AITA-style posts) and is less sure on dry or abstract ones. When auto-detection guesses wrong, set `emotion` and `hookText` directly. # Actor input Schema ## `title` (type: `string`): The video title or story headline (e.g. an AITA/TIFU title). Drives emotion + hook text. ## `story` (type: `string`): Full story or script text for richer emotion detection and hook extraction. ## `subreddit` (type: `string`): If 'amitheasshole', the hook is fixed to 'AM I THE A-HOLE ?'. Otherwise informs hook style. ## `aspectRatio` (type: `string`): 9:16 for Shorts/Reels/TikTok, 16:9 for YouTube long-form, 1:1 for square. ## `emotion` (type: `string`): Force a facial emotion instead of auto-detecting from the text. ## `hookText` (type: `string`): Force the burned-in headline text. Leave empty to auto-derive from the title/story. ## `gender` (type: `string`): Bias the generated face, e.g. 'feminine' or 'masculine'. Leave empty for model default. ## `burnText` (type: `boolean`): Overlay the bold hook headline on the lower third. Turn off to get the raw face image only. ## `openaiApiKey` (type: `string`): Your OpenAI key for image generation (gpt-image-1). Kept private. ## `imageModel` (type: `string`): Image model name. Default gpt-image-1. ## `imageQuality` (type: `string`): gpt-image-1 quality: low / medium / high. ## `imageBaseUrl` (type: `string`): OpenAI-compatible images base URL. Default https://api.openai.com/v1. ## Actor input object example ```json { "title": "AITA for refusing to pay for my sister's wedding?", "aspectRatio": "9:16", "burnText": true, "imageModel": "gpt-image-1", "imageQuality": "high" } ``` # Actor output Schema ## `results` (type: `string`): Result rows / metadata are stored in the default dataset (one row per item). ## `files` (type: `string`): Generated media/files (video, audio, images, captions) are stored in the default key-value store. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "title": "AITA for refusing to pay for my sister's wedding?" }; // Run the Actor and wait for it to finish const run = await client.actor("dami_studio/viral-thumbnail-generator").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "title": "AITA for refusing to pay for my sister's wedding?" } # Run the Actor and wait for it to finish run = client.actor("dami_studio/viral-thumbnail-generator").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "title": "AITA for refusing to pay for my sister'\''s wedding?" }' | apify call dami_studio/viral-thumbnail-generator --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=dami_studio/viral-thumbnail-generator", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "AI Thumbnail Generator", "description": "Turn any title or story into a scroll-stopping thumbnail: an AI emotional close-up face with a bold burned-in hook headline. Auto-detects emotion and writes the hook, or set your own. 9:16/16:9/1:1. For YouTube, Shorts, TikTok/Reels covers, ads, course covers, blog headers — any content.", "version": "0.1", "x-build-id": "yFPPiyNWwAnVat2Zu" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dami_studio~viral-thumbnail-generator/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dami_studio-viral-thumbnail-generator", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/dami_studio~viral-thumbnail-generator/runs": { "post": { "operationId": "runs-sync-dami_studio-viral-thumbnail-generator", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/dami_studio~viral-thumbnail-generator/run-sync": { "post": { "operationId": "run-sync-dami_studio-viral-thumbnail-generator", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "title": { "title": "Title / headline", "type": "string", "description": "The video title or story headline (e.g. an AITA/TIFU title). Drives emotion + hook text." }, "story": { "title": "Story / script (optional)", "type": "string", "description": "Full story or script text for richer emotion detection and hook extraction." }, "subreddit": { "title": "Subreddit (optional)", "type": "string", "description": "If 'amitheasshole', the hook is fixed to 'AM I THE A-HOLE ?'. Otherwise informs hook style." }, "aspectRatio": { "title": "Aspect ratio", "enum": [ "9:16", "16:9", "1:1" ], "type": "string", "description": "9:16 for Shorts/Reels/TikTok, 16:9 for YouTube long-form, 1:1 for square.", "default": "9:16" }, "emotion": { "title": "Emotion (optional override)", "enum": [ "", "betrayal", "rage", "shock", "disgust", "heartbreak", "fear", "guilt", "defiance" ], "type": "string", "description": "Force a facial emotion instead of auto-detecting from the text." }, "hookText": { "title": "Hook text (optional override)", "type": "string", "description": "Force the burned-in headline text. Leave empty to auto-derive from the title/story." }, "gender": { "title": "Face gender (optional)", "type": "string", "description": "Bias the generated face, e.g. 'feminine' or 'masculine'. Leave empty for model default." }, "burnText": { "title": "Burn hook text onto image", "type": "boolean", "description": "Overlay the bold hook headline on the lower third. Turn off to get the raw face image only.", "default": true }, "openaiApiKey": { "title": "OpenAI API key (BYO)", "type": "string", "description": "Your OpenAI key for image generation (gpt-image-1). Kept private." }, "imageModel": { "title": "Image model (advanced)", "type": "string", "description": "Image model name. Default gpt-image-1.", "default": "gpt-image-1" }, "imageQuality": { "title": "Image quality (advanced)", "enum": [ "low", "medium", "high" ], "type": "string", "description": "gpt-image-1 quality: low / medium / high.", "default": "high" }, "imageBaseUrl": { "title": "Image base URL (advanced)", "type": "string", "description": "OpenAI-compatible images base URL. Default https://api.openai.com/v1." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```