# Bulk AI Image Generator (NO API) (`fayoussef/bulk-ai-image-generator`) Actor Generate hundreds of AI images in one run from a list of prompts using top OpenRouter models (Gemini, GPT Image, Seedream, Flux...). - **URL**: https://apify.com/fayoussef/bulk-ai-image-generator.md - **Developed by:** [youssef farhan](https://apify.com/fayoussef) (community) - **Categories:** AI, Developer tools, Automation - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $8.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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 ## Bulk AI Image Generator — Generate Hundreds of AI Images from Prompts (OpenRouter) **Turn a list of text prompts into a gallery of AI-generated images in a single run.** This Apify Actor lets you pick from the top image-generation models — Google **Gemini 3.1 Flash / 3 Pro / 2.5 Flash Image** ("Nano Banana", "Nano Banana Pro") and **OpenAI GPT-5 / GPT-5.4 Image** — then generates, stores, and tabulates every image for you. **No API keys to manage:** model usage runs on your Apify credit via the official [apify/openrouter](https://apify.com/apify/openrouter) proxy, plus a small per-image fee. > **Bulk image generation, batch AI art, prompt-to-image automation, text-to-image API, AI image generator at scale** — all from one Actor. --- ### ✨ What it does - **Batch generation** — feed it a list of prompts and it produces one (or many) images per prompt. - **Top models, your choice** — select from a curated list of leading OpenRouter image models, or paste any custom model ID. - **Controllable output** — set aspect ratio (1:1, 16:9, 9:16, …) and resolution (0.5K → 4K). - **Variations** — generate up to 10 variations per prompt with one click. - **Clean results** — every image is stored in the run's key-value store and exposed as a public URL in a tidy dataset table you can preview, export (CSV/JSON/Excel), or pull via API. - **Fast & concurrent** — generates many images in parallel (configurable `concurrency`) instead of one at a time. - **Migration-safe** — progress is persisted continuously, so if Apify migrates or restarts the run it resumes where it left off without re-generating (or re-charging for) finished images. - **Resilient** — automatic retries with backoff on rate limits (429) and server errors; a single failed prompt is logged and skipped, never crashing the whole run. ### 🤔 Why use it You already have prompts. You don't want to: write API glue code, handle base64 decoding, manage rate limits, or click "generate" 300 times. This Actor does the boring part and hands you a downloadable dataset of images with full metadata. --- ### 🚀 Quick start 1. Open this Actor on Apify. **No API key needed** — model access runs on your Apify credit through the apify/openrouter proxy. 2. Add your **Prompts** (one per line). 3. Pick a **model**, **aspect ratio**, and **resolution**. 4. Click **Start**. When the run finishes, open the **Dataset** tab to preview and download your images. #### Input example ```json { "prompts": [ "A photorealistic golden retriever puppy in a sunlit meadow, shallow depth of field", "A minimalist flat-design mountain logo inside a circle, blue and white", "A cyberpunk city street at night, neon reflections on wet pavement" ], "model": "google/gemini-2.5-flash-image", "systemPrompt": "Cohesive flat-design illustration style, soft pastel palette", "aspectRatio": "16:9", "imageSize": "2K", "imagesPerPrompt": 2, "maxItems": 50 } ```` #### Output sample Each dataset item looks like this: ```json { "index": 0, "prompt": "A photorealistic golden retriever puppy in a sunlit meadow, shallow depth of field", "model": "google/gemini-3.1-flash-image-preview", "aspectRatio": "16:9", "imageSize": "2K", "imageUrl": "https://api.apify.com/v2/key-value-stores/XXXX/records/image-00000.png", "contentType": "image/png", "fileExtension": "png", "fileSizeBytes": 1742310, "description": "A golden retriever puppy sitting in tall grass...", "success": true } ``` The `imageUrl` points at the image binary stored in the run's key-value store. The **Overview** dataset view renders these as thumbnails. *** ### 💰 Cost You pay **the Actor's flat per-image fee + the exact OpenRouter cost** of each generated image, **rounded up to the nearest $0.00001**. The OpenRouter cost depends on the model and resolution you pick, so the total scales precisely with your usage. - **Actor fee** — a small fixed charge per generated image (the `apify-default-dataset-item` pay-per-event, charged automatically for every image pushed to the dataset). - **OpenRouter cost** — the real model/compute cost of the image, passed through and rounded up to the nearest **$0.00001**. > ⚠️ **Free Apify plan users are charged 10× the AI token (OpenRouter) cost.** Upgrade to any paid Apify plan for standard (1×) token pricing. Free plans are also capped at 10 images per run. *** ### 🎯 Use cases - **E-commerce** — generate product mockups, lifestyle shots, and ad creatives in bulk. - **Marketing & social** — produce a month of on-brand social posts from a content calendar of prompts. - **Game & app assets** — icons, textures, concept art at scale. - **Blogging & SEO** — unique header images for every article. - **Design exploration** — fan out a single idea into dozens of variations and pick the best. - **Datasets** — build labeled synthetic image sets for ML experiments. *** ### ❓ FAQ **Do I need my own OpenRouter API key?** No. By default, model access is routed through Apify's official [apify/openrouter](https://apify.com/apify/openrouter) proxy and billed as Apify credit using your run token — there's nothing to sign up for or paste. **Optionally**, if you'd rather use your own [OpenRouter](https://openrouter.ai) account, paste your key into the **OpenRouter API key** field (under Advanced settings): the Actor will then call OpenRouter directly and bill your OpenRouter account instead of your Apify credit. You still pay the small Actor per-image fee. **Which models are supported?** Any image-output model offered through the proxy. The dropdown curates the best ones (Gemini 2.5 Flash / 3.1 Flash / 3 Pro Image, GPT-5 / GPT-5.4 Image); the **Custom model ID** field accepts any other (see the [image-model list](https://openrouter.ai/models?fmt=cards\&output_modalities=image)). **Why did a prompt come back as text instead of an image?** Some chat-capable image models will answer a terse prompt (e.g. "flying monkey") with a clarifying question instead of drawing. This Actor sends a built-in system instruction forcing the model to always render an image; you can reinforce it with your own **System prompt**. Gemini models are the most reliable for this — switch to one if an OpenAI model keeps replying with text. **Where are my images?** Each image is saved in the run's key-value store and linked from the dataset via `imageUrl`. Export the dataset as JSON/CSV/Excel, or download images directly from the links. **What happens if a prompt fails or is rate-limited?** The client retries automatically with backoff (respecting `Retry-After`). If it still fails, that single image is logged and skipped — the rest of the run continues and you are not charged for it. **Can I control spend?** Yes — set **Max images** to hard-cap a run, and set a run-level spend limit in Apify. The Actor stops pushing once the budget is reached. *** ### 🔒 Responsible use This Actor is a thin automation layer over OpenRouter's models. You are responsible for your prompts and the images you generate, and for complying with [OpenRouter's terms](https://openrouter.ai/terms) and the underlying model providers' usage policies. Do not generate content that is illegal, infringing, deceptive, or that depicts real people without consent. Respect copyright and personality rights. *** ### 🛠️ Monetization setup (Actor owner) After `apify push`, configure pricing in **Apify Console → Actor → Publication → Monetization**: 1. Pricing model: **Pay per event**. 2. Add events with names **exactly matching** the code: - `apify-actor-start` → keep the **default** price. - `apify-default-dataset-item` → the per-image fee (this is the synthetic per-result event; the platform charges it automatically on every `push_data`). 3. Publish. The event name in [`src/main.py`](src/main.py) (`DATASET_ITEM_EVENT`) must match the Console exactly. > Do **not** set prices in `actor.json` — Apify reads pay-per-event prices from the Console only. # Actor input Schema ## `prompts` (type: `array`): One text prompt per image you want to generate. Each prompt can be combined with the 'Images per prompt' setting to create multiple variations. ## `model` (type: `string`): Which OpenRouter image-generation model to use. Defaults to Gemini 2.5 Flash Image (reliable, handles terse prompts well). Use 'Custom model ID' below to use any other OpenRouter model. ## `systemPrompt` (type: `string`): Optional extra instructions applied to every image (e.g. a consistent style, brand, or quality directive). This is appended to the built-in instruction that forces the model to always render an image and never reply with text. ## `customModelId` (type: `string`): Optional. Any OpenRouter model ID with image output, e.g. 'google/gemini-2.5-flash-image'. Overrides the 'Image model' selection above. See https://openrouter.ai/models?fmt=cards\&output\_modalities=image. ## `aspectRatio` (type: `string`): Aspect ratio of the generated images. Support varies by model; ignored by models that do not accept it. ## `imageSize` (type: `string`): Output resolution. Higher resolutions cost more OpenRouter credit. Support varies by model. ## `imagesPerPrompt` (type: `integer`): How many image variations to generate for each prompt (1-10). ## `concurrency` (type: `integer`): How many images to generate in parallel. Higher is faster but may hit rate limits sooner (1-20). ## `maxItems` (type: `integer`): Optional hard cap on the total number of images generated in this run, useful for controlling spend. Leave empty to generate one image for every prompt × images-per-prompt. ## `openRouterApiKey` (type: `string`): Optional. Bring your own OpenRouter API key to call OpenRouter directly and bill your own OpenRouter account. Leave empty to use the built-in apify/openrouter proxy (billed as Apify credit — no key needed). ## `proxyBaseUrl` (type: `string`): Advanced. Override the API base URL. Leave empty to use the default (apify/openrouter proxy, or https://openrouter.ai/api/v1 when an OpenRouter API key is provided). ## Actor input object example ```json { "prompts": [ "A cyberpunk city street at night, neon reflections on wet pavement" ], "model": "google/gemini-2.5-flash-image", "aspectRatio": "1:1", "imageSize": "1K", "imagesPerPrompt": 1, "concurrency": 6 } ``` # Actor output Schema ## `images` (type: `string`): The dataset of generated images with prompts, model metadata and public image URLs. # 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 = { "prompts": [ "A photorealistic golden retriever puppy sitting in a sunlit meadow, shallow depth of field", "A minimalist flat-design logo of a mountain inside a circle, blue and white" ], "systemPrompt": "" }; // Run the Actor and wait for it to finish const run = await client.actor("fayoussef/bulk-ai-image-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 = { "prompts": [ "A photorealistic golden retriever puppy sitting in a sunlit meadow, shallow depth of field", "A minimalist flat-design logo of a mountain inside a circle, blue and white", ], "systemPrompt": "", } # Run the Actor and wait for it to finish run = client.actor("fayoussef/bulk-ai-image-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 '{ "prompts": [ "A photorealistic golden retriever puppy sitting in a sunlit meadow, shallow depth of field", "A minimalist flat-design logo of a mountain inside a circle, blue and white" ], "systemPrompt": "" }' | apify call fayoussef/bulk-ai-image-generator --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=fayoussef/bulk-ai-image-generator", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Bulk AI Image Generator (NO API)", "description": "Generate hundreds of AI images in one run from a list of prompts using top OpenRouter models (Gemini, GPT Image, Seedream, Flux...).", "version": "0.1", "x-build-id": "M5elEK0iHjgR7Q39A" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/fayoussef~bulk-ai-image-generator/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-fayoussef-bulk-ai-image-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/fayoussef~bulk-ai-image-generator/runs": { "post": { "operationId": "runs-sync-fayoussef-bulk-ai-image-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/fayoussef~bulk-ai-image-generator/run-sync": { "post": { "operationId": "run-sync-fayoussef-bulk-ai-image-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", "required": [ "prompts" ], "properties": { "prompts": { "title": "Prompts", "type": "array", "description": "One text prompt per image you want to generate. Each prompt can be combined with the 'Images per prompt' setting to create multiple variations.", "items": { "type": "string" } }, "model": { "title": "Image model", "enum": [ "google/gemini-2.5-flash-image", "google/gemini-3.1-flash-image-preview", "google/gemini-3-pro-image-preview", "openai/gpt-5-image", "openai/gpt-5-image-mini", "openai/gpt-5.4-image-2" ], "type": "string", "description": "Which OpenRouter image-generation model to use. Defaults to Gemini 2.5 Flash Image (reliable, handles terse prompts well). Use 'Custom model ID' below to use any other OpenRouter model.", "default": "google/gemini-2.5-flash-image" }, "systemPrompt": { "title": "System prompt (optional)", "type": "string", "description": "Optional extra instructions applied to every image (e.g. a consistent style, brand, or quality directive). This is appended to the built-in instruction that forces the model to always render an image and never reply with text." }, "customModelId": { "title": "Custom model ID (advanced)", "type": "string", "description": "Optional. Any OpenRouter model ID with image output, e.g. 'google/gemini-2.5-flash-image'. Overrides the 'Image model' selection above. See https://openrouter.ai/models?fmt=cards&output_modalities=image." }, "aspectRatio": { "title": "Aspect ratio", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "21:9" ], "type": "string", "description": "Aspect ratio of the generated images. Support varies by model; ignored by models that do not accept it.", "default": "1:1" }, "imageSize": { "title": "Image resolution", "enum": [ "0.5K", "1K", "2K", "4K" ], "type": "string", "description": "Output resolution. Higher resolutions cost more OpenRouter credit. Support varies by model.", "default": "1K" }, "imagesPerPrompt": { "title": "Images per prompt", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many image variations to generate for each prompt (1-10).", "default": 1 }, "concurrency": { "title": "Concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many images to generate in parallel. Higher is faster but may hit rate limits sooner (1-20).", "default": 6 }, "maxItems": { "title": "Max images (optional cap)", "minimum": 1, "type": "integer", "description": "Optional hard cap on the total number of images generated in this run, useful for controlling spend. Leave empty to generate one image for every prompt × images-per-prompt." }, "openRouterApiKey": { "title": "OpenRouter API key (optional)", "type": "string", "description": "Optional. Bring your own OpenRouter API key to call OpenRouter directly and bill your own OpenRouter account. Leave empty to use the built-in apify/openrouter proxy (billed as Apify credit — no key needed)." }, "proxyBaseUrl": { "title": "OpenRouter proxy base URL (advanced)", "type": "string", "description": "Advanced. Override the API base URL. Leave empty to use the default (apify/openrouter proxy, or https://openrouter.ai/api/v1 when an OpenRouter API key is provided)." } } }, "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 } } } } } } } } } } ```