DEV Community: Sherwood

Bulk-generate images from a list of prompts with one API call (FLUX, no API key)

Sherwood — Mon, 19 Oct 2026 17:44:52 +0000

Generating one image is easy: open any web playground, type a prompt, download the file. Generating two hundred images from inside a pipeline is a different job. The typical cases: product visuals for a catalog where each row of a spreadsheet needs its own picture, illustrations for a batch of blog posts or slides, placeholder art for a game or an app, creative variations for ads where you want four takes per concept.

What you want there is boring: a list of prompts in, a list of image URLs out, the size and the seed for each so you can reproduce it, and a clear signal for the ones that failed. This post compares the usual ways to batch-generate images, then shows how to do it with one API call from curl, Python, JavaScript, n8n and an AI agent.

Why batch image generation gets annoying

Self-hosting FLUX or Stable Diffusion. Full control, no per-image fee, any LoRA you like. In exchange, you need a GPU with enough VRAM, a queue, a way to serve the files, and someone to keep it running. It pays off at high, steady volume, and not before.

Calling an inference API (fal, Replicate, Together) directly. Close to the metal and fast, but now your pipeline owns an API key, a retry policy, per-image polling, and a place to store the output files. Multiply that by every workflow that needs images.

The big-model APIs (OpenAI, Google). Great models, but you still sign up for a key, and the bill is per account, not per run. For a no-code tool or an agent, "go create an account and wire a secret" is where the automation dies.

Looping over a single-image endpoint. Most hosted generators take one prompt per call. Two hundred prompts means two hundred calls, your own concurrency control, and your own bookkeeping of which output belongs to which prompt.

The pattern that removes all of this: one call that takes the whole list, runs the model, stores the files, and returns one record per image with its URL. That is what an Apify Actor does, and the rest of this post uses one I maintain: Bulk AI Image Generator (FLUX.2 Klein 9B by default, FLUX Schnell in fast mode).

A batch image generator behind one API call

Step 1: get a token

Create a free Apify account and copy your API token from Settings → Integrations. There is no image-model key to manage: the model runs inside the Actor.

Step 2: the input

The input is a JSON object. Everything is optional; the default input generates two sample images so you can see the output shape before sending your own prompts.

{
  "prompts": [
    "A ceramic coffee mug on a wooden table, soft morning light, product photography",
    "Minimal flat illustration of a paper plane flying over pastel mountains"
  ],
  "imageSize": "square_hd",
  "quality": "standard",
  "imagesPerPrompt": 1,
  "outputFormat": "png"
}

prompts — the list. A single string in prompt, or the aliases texts and queries, work too; everything is merged and deduplicated.
imageSize — square_hd (1024×1024), landscape_4_3, landscape_16_9, portrait_4_3, portrait_16_9, square; or exact width and height in pixels (256 to 2048).
quality — standard is FLUX.2 Klein 9B; fast is FLUX Schnell, cheaper and quicker, for drafts and placeholders.
imagesPerPrompt — up to 4 variations per prompt, each with its own seed.
seed — set it to reproduce a run; every result carries the seed it used either way.
maxPrompts — hard cap per run (default 100, up to 1,000), so a malformed input cannot surprise you.

Step 3: call it with curl

curl -s -X POST \
  "https://api.apify.com/v2/actors/sherwood~image-generator-batch/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompts": ["A ceramic coffee mug on a wooden table, product photography"]}'

The call blocks until the run finishes and returns the dataset items directly.

Step 4: Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("sherwood/image-generator-batch").call(run_input={
    "prompts": [
        "A ceramic coffee mug on a wooden table, product photography",
        "Minimal flat illustration of a paper plane over pastel mountains",
    ],
    "imageSize": "landscape_16_9",
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    if item["status"] == "ok":
        print(item["prompt"][:40], "->", item["outputUrl"])
    else:
        print(item["prompt"][:40], "FAILED:", item["error"])

Step 5: JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('sherwood/image-generator-batch').call({
    prompts: ['A ceramic coffee mug on a wooden table, product photography'],
    imagesPerPrompt: 4,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const item of items) {
    console.log(item.status, item.variant, item.outputUrl ?? item.error);
}

What comes back

One dataset item per generated image:

{
  "index": 0,
  "variant": 0,
  "prompt": "A ceramic coffee mug on a wooden table, product photography",
  "outputUrl": "https://api.apify.com/v2/key-value-stores/abc123/records/image-0000-0.png",
  "width": 1024,
  "height": 1024,
  "seed": 1545164682,
  "model": "fal-ai/flux-2/klein/9b",
  "format": "png",
  "durationMs": 1666,
  "status": "ok",
  "error": null
}

index is the position of the prompt in your input and variant the variation number, so matching outputs back to your own rows is a sort, not a guess. seed makes any image reproducible: send the same prompt, size and seed, get the same image.

Failed prompts come back as items, and are not charged

A prompt the safety checker refuses, or an upstream error, produces an item with "status": "error" and the reason in error. It costs nothing, and nothing is silently dropped: you always get as many answers as questions. The safety checker is always on; this Actor is not a way around model content rules.

Using it from n8n

The wiring is three nodes around the official Apify node (install "Apify" from the community nodes if you don't have it). Read a prompt column from a Google Sheet; a Code node collects the non-empty prompts into one list; the Apify node runs sherwood~image-generator-batch with that list as prompts; a last Code node sorts the results by index to put each image next to its prompt, and a Google Sheets node writes image_url, width, height, seed and status back to each row. Because the whole sheet goes in one Actor call, the workflow runs once per batch, not once per row.

Using it from an AI agent (MCP)

Add the Apify MCP server to your agent and it can call the Actor like any tool: the input above, as arguments; the dataset items, as the result. Nothing in the input is required, so a one-line instruction ("generate an image for each of these ten product names") maps cleanly onto one call.

The Actor is also eligible for agentic payments (x402, Skyfire, MPP): an agent can run it and pay per request without an Apify account at all.

Pricing at the time of writing

Image generated — $0.01 per image delivered, 1024×1024 included. Larger sizes add $0.01 per started extra megapixel.
Failed or safety-flagged prompts: free.
No subscription, no minimum. Apify's free plan is enough to try it.

Two hundred catalog images cost about $2. Set a maximum cost per run in Apify and the Actor stops cleanly at the limit, reporting what remains instead of failing.

Limits

Output files live in the run's key-value store and follow your Apify account's data retention; copy them out if you need them long-term.
imagesPerPrompt tops out at 4, sizes at 2048 px per side.
The model is FLUX.2 Klein 9B (or Schnell). If your brief needs a specific aesthetic from another model, this is not that.

When I wouldn't use it

For one image now and then, a free web playground is simpler. For a style that depends on a particular model or a custom LoRA, self-hosting or a direct inference API gives you the control this Actor deliberately hides. And at very high, steady volume — tens of thousands of images a month, every month — a rented GPU beats any per-image price. Everywhere between those: a list in, a list out, one call.

How to upscale images in bulk with one API call (2x or 4x, no GPU)

Sherwood — Mon, 05 Oct 2026 18:26:27 +0000

Upscaling one image is easy: open a desktop app, drop the file, save the result. Upscaling a few hundred images from inside a pipeline is a different job. The typical cases: a supplier feed full of 600×600 product photos when the marketplace wants larger ones, AI-generated images that are too small for print, avatars and thumbnails pulled by a scraper that look soft at full width.

What you want there is boring: a list of URLs in, a list of larger files out, the new width and height for each, and a clear signal for the ones that failed. This post compares the usual ways to increase image resolution in bulk, then shows how to do it with one API call from curl, Python, JavaScript, n8n and an AI agent.

Why bulk upscaling gets annoying

Self-hosting a super-resolution model. Open models such as Real-ESRGAN give you full control and no per-image fee. In exchange, you need a GPU, a queue, a way to move files in and out, and someone to keep it running. It pays off at high, steady volume.

Desktop apps like Upscayl. Free, open source and good at the job, folders included. They run on the machine of whoever clicks the button, with that machine's GPU, which makes them a poor fit for a server-side pipeline.

Hosted model APIs. Providers such as Replicate or fal remove the GPU. You still sign up, manage a provider key and write the glue: one request per image, a concurrency limit, retries, storage for the results, matching each output to its input, and a plan for when image 37 of 200 fails.

SaaS upscalers. Polished web apps, usually sold as a subscription or credit packs, and designed around someone uploading files in a browser.

Option	GPU on your side	What you manage	A list of URLs in one call	Billing
Self-hosted model	Yes	Model, queue, storage, uptime	If you build it	Your infrastructure
Desktop app (Upscayl)	Yes, local	Running it by hand	Folders, from the app	Free, open source
Hosted model API	No	Provider key, per-image loop, retries	Usually one image per request	Pay per use
SaaS upscaler	No	Account, uploads	Depends on the product	Usually subscription or credits
Apify actor (below)	No	Apify token	Yes	Per image delivered, failures free

A batch image upscaler behind one API call

What the first four rows leave open is hosted convenience (no GPU, no model-provider key) without writing the per-image glue yourself. That's the case the actor below covers. It's Image Upscaler API on the Apify Store (sherwood/image-upscaler-batch): you send a list of image URLs, it runs each one through SeedVR2, an AI super-resolution model, and writes one result per image to a dataset.

Disclosure: I maintain the Apify actor used below.

The only credential you handle is your Apify API token, and there's no subscription to the actor.

Step 1: get a token

Create an Apify account, copy your API token from Settings > API & Integrations in the Apify Console, and export it as APIFY_TOKEN; every example below reads it from there.

Step 2: the input

{
  "imageUrls": [
    "https://example.com/products/chair-600.jpg",
    "https://example.com/products/lamp-600.png"
  ],
  "scale": "2",
  "outputFormat": "jpg",
  "maxOutputMegapixels": 16
}

imageUrls: public JPG, PNG or WebP URLs. The aliases imageUrl, urls, images and startUrls are merged into it and duplicates are removed, which helps when the list comes from another tool.
scale: "2" doubles width and height, "4" quadruples them. It's a string in the input schema, and Apify validates API input against the schema, so send "4", not 4.
outputFormat: jpg (default), png (keeps transparency) or webp.
maxOutputMegapixels: a cap on output size, default 16. An image whose upscaled size would exceed it is upscaled to the cap instead. For reference, 4 MP is about 2000×2000.
maxImages: stop after this many images, default 100.

Every field is optional: an empty input upscales two sample images, a quick way to see the output shape.

Step 3: call it with curl

curl -X POST \
  "https://api.apify.com/v2/actors/sherwood~image-upscaler-batch/run-sync-get-dataset-items?maxTotalChargeUsd=1" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrls": [
      "https://example.com/products/chair-600.jpg",
      "https://example.com/products/lamp-600.png"
    ],
    "scale": "2"
  }'

run-sync-get-dataset-items starts the run, waits for it, and returns the dataset items as a JSON array. The maxTotalChargeUsd query parameter caps what the run can cost: when the cap is reached, the actor stops cleanly and the remaining images are reported, not processed.

One constraint: synchronous endpoints wait at most 300 seconds, then return HTTP 408 while the run carries on. Processing typically takes 5 to 25 seconds per image, 4 images in parallel, so keep synchronous calls to a few dozen images. For bigger lists, use a client library: it waits as long as the run takes.

Step 4: Python

pip install apify-client. This targets version 3 of the client, where call() returns a typed Run object. Older examples that read run["defaultDatasetId"] were written for the 1.x and 2.x clients, which returned dicts.

import os

from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])

run = client.actor("sherwood/image-upscaler-batch").call(
    run_input={
        "imageUrls": [
            "https://example.com/products/chair-600.jpg",
            "https://example.com/products/lamp-600.png",
        ],
        "scale": "4",
        "outputFormat": "png",
    }
)
if run is None or run.status != "SUCCEEDED":
    raise RuntimeError("The actor run did not finish successfully")

items = client.dataset(run.default_dataset_id).list_items().items
for item in sorted(items, key=lambda i: i["index"]):
    if item["status"] == "ok":
        print(f'{item["inputUrl"]} -> {item["outputUrl"]} ({item["width"]}x{item["height"]})')
    else:
        print(f'FAILED {item["inputUrl"]}: {item["error"]}')

Sorting by index puts the results back in input order. To cap the cost from Python, pass max_total_charge_usd=Decimal("2") (from the decimal module) to call().

Step 5: JavaScript

npm install apify-client, then run this as an ES module (node upscale.mjs):

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });

const run = await client.actor('sherwood/image-upscaler-batch').call(
  {
    imageUrls: ['https://example.com/products/chair-600.jpg'],
    scale: '2',
    outputFormat: 'webp',
  },
  { maxTotalChargeUsd: 1 },
);
if (run.status !== 'SUCCEEDED') throw new Error(`Run ended with status ${run.status}`);

const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const item of items) {
  if (item.status === 'ok') console.log(item.outputUrl, `${item.width}x${item.height}`);
  else console.log('FAILED', item.inputUrl, item.error);
}

What comes back

One item per image, like this example from the README:

{
  "index": 0,
  "inputUrl": "https://example.com/product-small.jpg",
  "outputUrl": "https://api.apify.com/v2/key-value-stores/abc123/records/upscaled-0000.jpg",
  "width": 2048,
  "height": 2048,
  "megapixels": 4.19,
  "scale": "2",
  "format": "jpg",
  "model": "fal-ai/seedvr/upscale/image",
  "durationMs": 9120,
  "status": "ok",
  "error": null
}

index is the image's position in your input list, so matching results to inputs never depends on order. outputUrl, width, height and megapixels describe the upscaled file; model and durationMs tell you what ran and how long it took.

Failed images come back as items, and are not charged

An unreachable URL, a file that isn't an image, or an input over 25 MB doesn't break the batch. That image comes back with "status": "error" and the reason in error, and it is never charged. In practice: filter on status, log the failures, and re-run just those URLs if the cause was temporary.

Using it from n8n

With the Apify node. Install the Apify community node (@apify/n8n-nodes-apify; on n8n Cloud it's listed among the verified community nodes) and add your token as an Apify API credential. Then:

An Apify node with the Run Actor operation: actor sherwood/image-upscaler-batch, the JSON above as custom input, Wait for finish on.
A second Apify node that reads the dataset items, with Dataset ID set to the defaultDatasetId field returned by the first node.

With the HTTP Request node. POST to the run-sync URL from the curl example, with a Header Auth credential (name Authorization, value Bearer <your token>) and the input as the JSON body. n8n turns the returned array into one item per image, so the next node runs once per upscaled file.

If your URLs arrive as separate n8n items, put an Aggregate node in front; otherwise n8n sends one request per item instead of one list. If you set the node's Timeout option, give it at least 300,000 ms.

Using it from an AI agent (MCP)

Apify's MCP server can expose a single actor as a tool. Add it to your MCP client with a tools filter:

{
  "mcpServers": {
    "image-upscaler": {
      "url": "https://mcp.apify.com?tools=sherwood/image-upscaler-batch"
    }
  }
}

On first connection, your browser opens so you can sign in to Apify. To skip the sign-in, send your token in an Authorization: Bearer header instead. With tools= set, the agent only gets this actor, as a tool named sherwood--image-upscaler-batch with the input schema above, plus helpers the server adds on its own (get-actor-run, get-dataset-items, get-key-value-store-record, abort-actor-run). Calling the actor tool returns the run metadata and a dataset ID; the agent then calls get-dataset-items to read the URLs.

Pricing at the time of writing

From the actor's README:

Image upscaled: $0.012 per image delivered, output up to 4 MP included.
Extra megapixel: $0.002 per started megapixel above 4 MP (a 4x upscale of a 1000×1000 photo is 16 MP, so 12 extra).
Failed, unreachable or non-image URLs: free.

Worked through: a 2x upscale of a 1000×1000 photo gives 2000×2000, which is 4 MP and costs $0.012. The 4x version costs $0.012 + 12 × $0.002 = $0.036. The example item above, 2048×2048 at 4.19 MP, starts a fifth megapixel, so it costs $0.014. maxOutputMegapixels bounds the extra-megapixel part, and a maximum cost per run bounds the total.

Limits

Inputs must be reachable over public http(s) URLs, up to 25 MB each. Local files need to go somewhere reachable first, for example a pre-signed URL from your bucket.
Output files live in the run's key-value store and follow your account's data retention, so copy the ones you want to keep.
Processing is typically 5 to 25 seconds per image, with 4 images in parallel.
maxImages defaults to 100, and the input schema allows up to 1,000 per run.

When I wouldn't use it

At high, steady volume, a self-hosted GPU can be cheaper per image, and it's the only option when images can't leave your network. If you already have an account with a model provider and the per-image glue written, the actor adds little: the model field shows the SeedVR2 endpoint it calls. For ten images and a laptop with a decent GPU, Upscayl does the job.

The actor is for the case in between: lists of URLs inside a pipeline or an agent, where you want a result or an error per image without running anything yourself. Actor page: apify.com/sherwood/image-upscaler-batch.