> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/mcp/recipes/batch.md).

# Batch-generate 20 to 500 assets

Turn a list of products, variants or scenes into 20 to 500 FLORA generations from your agent: quote the batch, fire in chunks of 20, poll, and retry only what failed.

Hand your agent a list (SKUs, markets, scenes, a CSV) and one style, and [FLORA MCP](https://flora.ai/mcp) returns one asset per row on a single canvas. Use this recipe when the job is a list. For a handful of one-off images, [Generate an image or video](https://docs.flora.ai/mcp/recipes/generate.md) is simpler; when each row needs a saved multi-step workflow, run one [Technique](https://docs.flora.ai/mcp/recipes/run-a-technique.md) per row with the same method.

**Works in:** Claude · Claude Code · ChatGPT · Codex · Cursor (a coding agent such as Claude Code, Codex or Cursor is the most comfortable for 100+ rows)

**You need:** a connected client, a workspace, about $0.07 per image with Nano Banana 2 at 1K (about $7 for 100)

**Use when:** the input is a list, spreadsheet or folder and you want one output per row in one consistent style.

**Don't use when:** you need one item, or each row needs a genuinely different treatment (that's several batches).

## Ask your agent

> Use FLORA to make one studio product shot per row of the list below, all in one style: seamless warm-grey backdrop, soft light from camera left, subtle contact shadow, square. Put them in a new project called "Fall PDP". Show me the cost first and wait for my OK, then fire them in batches of 20 and retry only the items that fail. List: \[paste your list or CSV]

<a href="https://claude.ai/new?q=Use%20FLORA%20to%20make%20one%20studio%20product%20shot%20per%20row%20of%20the%20list%20below%2C%20all%20in%20one%20style%3A%20seamless%20warm-grey%20backdrop%2C%20soft%20light%20from%20camera%20left%2C%20subtle%20contact%20shadow%2C%20square.%20Put%20them%20in%20a%20new%20project%20called%20%22Fall%20PDP%22.%20Show%20me%20the%20cost%20first%20and%20wait%20for%20my%20OK%2C%20then%20fire%20them%20in%20batches%20of%2020%20and%20retry%20only%20the%20items%20that%20fail.%20List%3A%20%5Bpaste%20your%20list%20or%20CSV%5D" class="button primary">Open in Claude</a> <a href="https://chatgpt.com/?q=Use%20FLORA%20to%20make%20one%20studio%20product%20shot%20per%20row%20of%20the%20list%20below%2C%20all%20in%20one%20style%3A%20seamless%20warm-grey%20backdrop%2C%20soft%20light%20from%20camera%20left%2C%20subtle%20contact%20shadow%2C%20square.%20Put%20them%20in%20a%20new%20project%20called%20%22Fall%20PDP%22.%20Show%20me%20the%20cost%20first%20and%20wait%20for%20my%20OK%2C%20then%20fire%20them%20in%20batches%20of%2020%20and%20retry%20only%20the%20items%20that%20fail.%20List%3A%20%5Bpaste%20your%20list%20or%20CSV%5D" class="button secondary">Open in ChatGPT</a>

{% hint style="info" %}
This recipe is the short version of the **flora-batch-generate** skill. Agents that have the skill follow it automatically; others can load it with `flora_discover_skills` (`name: "flora-batch-generate"`). See [FLORA MCP skills and plugins](https://docs.flora.ai/mcp/skills.md).
{% endhint %}

## What the agent does

{% hint style="warning" %}
**Cost rule.** Price first: call `flora_create_generations` with `quote: true` and show the user the cost in US dollars. Run the same request without `quote` only after they approve. On `insufficient_credits` or any `BILLING_*` error, stop and pass the message on. Don't retry. Check balance and spend with `flora_get_usage`. A failed run isn't charged; a retry is a new run and is billed again.
{% endhint %}

{% hint style="info" %}
**Polling rule.** Save every `run_id`. Wait at least 15 seconds between polls, or 2 seconds per run for bigger batches (40 seconds for 20 runs). Then read every `run_id` in one `flora_list_generations` call (up to 20 per call). For example: `flora_list_generations({"run_ids": ["run_a", "run_b"]})`. For Technique runs, also pass `"technique_id"`. Polling faster returns `429` or cooldown errors with `retry_after_seconds`.
{% endhint %}

{% stepper %}
{% step %}

### Plan: parse the list, fix the style, pick one model

* Parse the rows and confirm the count and a few sample rows with you. A misread column is free to fix now and paid to fix later.
* Build one style string and append each row's subject to it. That string is the whole consistency mechanism.
* Pick one model for the batch and read its parameters with `flora_list_models` and `model_id`. Use only the `params` names and values it returns; a mistyped value can silently fall back to the model's default and still bill.
* Put the batch in its own project (`flora_create_project`), so history reads and the canvas stay clean.
  {% endstep %}

{% step %}

### Quote the whole batch, then wait for approval

Rows with the same model and `params` cost the same, so the agent quotes one representative item and multiplies, or quotes every chunk if the `params` vary:

```json
{
  "quote": true,
  "generations": [
    {
      "project_id": "prj_abc",
      "type": "image",
      "prompt": "A matte black ceramic pour-over dripper. Studio product photo on a seamless warm-grey backdrop, soft light from camera left, subtle contact shadow, 85mm, centred, no props, no text",
      "model": "t2i-gemini-3.1-flash-image",
      "params": { "aspect_ratio": "1:1", "resolution": "1K" }
    }
  ]
}
```

It tells you plainly: "120 items × $0.072 = about $8.64. Proceed?" and waits.
{% endstep %}

{% step %}

### Fire in chunks of up to 20

`flora_create_generations` takes 1 to 20 items per call, so 120 rows is 6 calls. Within a call, every item starts at once.

```json
{
  "generations": [
    {
      "project_id": "prj_abc",
      "type": "image",
      "prompt": "A matte black ceramic pour-over dripper. Studio product photo on a seamless warm-grey backdrop, soft light from camera left, subtle contact shadow, 85mm, centred, no props, no text",
      "model": "t2i-gemini-3.1-flash-image",
      "params": { "aspect_ratio": "1:1", "resolution": "1K" }
    },
    {
      "project_id": "prj_abc",
      "type": "image",
      "prompt": "A brushed steel insulated water bottle. Studio product photo on a seamless warm-grey backdrop, soft light from camera left, subtle contact shadow, 85mm, centred, no props, no text",
      "model": "t2i-gemini-3.1-flash-image",
      "params": { "aspect_ratio": "1:1", "resolution": "1K" }
    }
  ]
}
```

The response keeps input order. Each entry has `index` and `ok`. A success also carries `run_id`, `node_id`, `model.model_id`, `estimated_seconds`, `charged_cost` (an estimate at start time), `project_id`, `canvas_url` and `poll_url`; a failure carries `error` and usually `status`. The longest `estimated_seconds` in a chunk is a good hint for when to make its first poll. The agent writes down a **`run_id` → row map** after every call (in a file if it has one, otherwise in the conversation). That map is the only link between a run and the row it came from.

Fire the chunks back to back; there's no need to pace them on a timer. Save each response's map before the next call. For very large lists, fire a wave of a few chunks (for example 100 rows), poll them, and fire the next wave as they finish, so polling stays inside the workspace's per-minute rate limit.
{% endstep %}

{% step %}

### Poll each chunk in one call

Each chunk is one `flora_list_generations` call with that chunk's `run_ids` (up to 20), no more often than the polling rule allows (40 seconds for 20 runs):

```json
{
  "run_ids": ["run_01", "run_02", "run_03", "run_04", "run_05", "run_06", "run_07", "run_08", "run_09", "run_10", "run_11", "run_12", "run_13", "run_14", "run_15", "run_16", "run_17", "run_18", "run_19", "run_20"]
}
```

Key on `status` only. `completed` with `outputs` means the asset exists; `failed` carries `error_code` and `error_message`; `pending` and `running` are still going. A failed run can also report `progress: 100`, so don't read that as success.
{% endstep %}

{% step %}

### Collect results and settle the cost

The agent reports one row per item, in your order, keyed by your SKU or filename:

| SKU   | Status    | Cost   | Output                                                 |
| ----- | --------- | ------ | ------------------------------------------------------ |
| PO-01 | completed | $0.072 | `https://media.flora.ai/…`                             |
| WB-04 | failed    | none   | `GENERATION_PROMPT_MODERATED`: needs a reworded prompt |

`charged_cost` can appear a little after a run completes. The agent re-reads the batch once everything is finished before it totals the cost, and calls the total a floor if any value is still missing. `flora_get_usage` shows the workspace's spend afterwards.
{% endstep %}

{% step %}

### Retry only what failed

A batch is not all-or-nothing. Never re-fire the whole batch: the items that succeeded already spent money.

| `error_code`                                                                                                                  | What to do                           |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `GENERATION_PROVIDER_TIMEOUT`, `GPU_PROVIDER_ERROR`, `GENERATION_GENERIC_ERROR`, `GENERATION_FAILED_TO_START`, `SERVER_ERROR` | Retry once, as a new item.           |
| `GENERATION_DOWNSTREAM_SERVICE_ERROR`, `GENERATION_QUEUE_TOO_LARGE`, `GENERATION_NO_RESULT`                                   | Wait a few minutes, then retry once. |
| `GENERATION_PROMPT_MODERATED`, `GENERATION_INVALID_PARAMS`, `GENERATION_INVALID_URL`                                          | Change the prompt or input first.    |
| `BILLING_*`, `ACCESS_*`                                                                                                       | Stop and tell you. Don't retry.      |

Read `error_message` as well as the code: a provider error sometimes wraps a safety refusal, and retrying it unchanged only fails the same way. Failed runs aren't charged, but every retry is a new generation and is billed if it succeeds.
{% endstep %}
{% endstepper %}

## Recover after a timeout

`flora_create_generations` has no idempotency key. If a create call times out or the conversation drops, some items may have started anyway, and firing them again bills twice. Before re-firing, the agent reads history for the batch's project, with the submitted prompts, 20 to 50 runs per page:

```json
{
  "project_id": "prj_abc",
  "include_inputs": true,
  "limit": 25
}
```

Without `run_ids`, `flora_list_generations` returns history newest first, and `include_inputs` adds each run's submitted prompt and references. The agent matches prompts to rows, fires only the rows with no run, and reads older pages by passing the response's `meta.next_cursor` as `cursor`.

`include_inputs` pages have a size budget of about 200 KB. Prompts longer than 2,000 characters come back trimmed (the entry is flagged `inputs.truncated`), and a page that still won't fit fails the whole call with "include\_inputs history exceeds the \~200 KB tool-result budget even as previews". When that happens:

1. Ask for a smaller page (`limit` of 10 or 20), and keep paging with `cursor`.
2. Narrow it with `status` (for example `"pending"` or `"running"` to see what's still in flight).
3. Or drop `include_inputs` and match on what history always returns: compare the runs created since the chunk was sent (`created_at`) with the `run_ids` you already saved. If the count doesn't settle which rows started, the agent asks you before re-firing anything.

## Check it worked

* The number of `completed` runs equals the number of rows, or the report names every row that didn't finish and why.
* The canvas shows one node per completed row. To lay them out, see [Put results on a canvas](https://docs.flora.ai/mcp/recipes/canvas.md).

## If it fails

| Symptom                                                                                 | Cause                                                                                                              | Fix                                                                                                                                                                                                 |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Runs fail with `BILLING_NOT_ENOUGH_CREDITS` (or another `BILLING_*` code) when you poll | The workspace ran out of balance mid-batch. Creates still return `ok: true`; the billing error shows up on the run | Stop firing. Every later item fails the same way. Report what finished and relay the message.                                                                                                       |
| Some entries `ok: false` with `input_validation_error`                                  | A bad `model`, key or ID on those items                                                                            | Fix and re-fire only those items. Nothing was charged for them.                                                                                                                                     |
| `429` or `rate_limited`                                                                 | Too many requests against the per-minute limit (counted against your credential's default workspace)               | Wait `retry_after_seconds` if the error has it; otherwise back off about 60 seconds. Then retry reads and continue with fewer chunks in flight. Don't blindly re-fire creates: check history first. |
| Rows stuck `running` long past `estimated_seconds`                                      | A slow or stuck provider                                                                                           | See the stuck-run guidance in [runs](https://docs.flora.ai/mcp/runs.md). Don't re-fire until history shows the run failed.                                                                          |
| Outputs drift in style across the batch                                                 | The style string changed between rows, or rows used different models                                               | Keep one style string and one model per batch; split real differences into separate batches.                                                                                                        |
| `unknown_error` on every item                                                           | Often a malformed `prj_` or `ws_` ID                                                                               | Check the IDs with `flora_get_project` before assuming an outage.                                                                                                                                   |

Related: [cost and limits](https://docs.flora.ai/mcp/cost-and-limits.md), [runs and polling](https://docs.flora.ai/mcp/runs.md), and the [flora-batch-generate skill](https://raw.githubusercontent.com/florafauna-ai/flora-mcp-skills/main/skills/flora-batch-generate/SKILL.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/mcp/recipes/batch.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
