> 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/tools/generations.md).

# Generation and run tools

Reference for the FLORA MCP tools that start image, video, audio, text and 3D generations, quote their cost, and poll their runs.

These [FLORA MCP](https://flora.ai/mcp) tools start generations and read their results. [`flora_create_generations`](#flora_create_generations) starts 1 to 20 runs in one call and lands each result on the project's canvas, and [`flora_list_generations`](#flora_list_generations) polls them. Quote first with `quote: true`, show the user the cost in US dollars, and run only after they approve.

For a worked example, see [Generate an image or video](https://docs.flora.ai/mcp/recipes/generate.md). For timeouts and failed runs, see [FLORA MCP runs](https://docs.flora.ai/mcp/runs.md).

{% 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 %}

| Tool                                                    | What it does                                                                                                   | Labels                                   |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| [`flora_create_generations`](#flora_create_generations) | Start 1 to 20 image, video, audio, text or 3D generations in one call, or price them first with `quote: true`. | writes, destructive, spends money, async |
| [`flora_list_generations`](#flora_list_generations)     | Read up to 20 runs by `run_id` in one call, or list generation history with cost and outputs.                  | read-only                                |
| [`flora_view_model3d`](#flora_view_model3d)             | Open an interactive 3D viewer for a 3D run, with GLB links and preview images.                                 | read-only                                |

## flora\_create\_generations <a href="#flora_create_generations" id="flora_create_generations"></a>

Start 1 to 20 image, video, audio, text or 3D generations in one call, or price them first with `quote: true`.

**Labels:** writes · destructive · spends money · async

**Shown in clients as:** Create generations

**Use when:** The user wants new images, video, audio, text or 3D from a prompt, optionally with canvas nodes as image or 3D references.

**Don't use when:** You want to animate an image that's on the canvas: canvas references to a video model are rejected with `input_validation_error` (HTTP 400), so add a video node wired to it with [`flora_add_to_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_add_to_canvas) and run it with [`flora_run_canvas_nodes`](https://docs.flora.ai/mcp/tools/canvas.md#flora_run_canvas_nodes). For a team's saved workflow, use [`flora_run_technique`](https://docs.flora.ai/mcp/tools/techniques-and-actions.md#flora_run_technique).

{% hint style="info" %}
To animate a photo from a URL instead, pass it in `params` under the image field [`flora_list_models`](https://docs.flora.ai/mcp/tools/models-and-loras.md#flora_list_models) names for that model (`image_url` or `image_urls`).
{% endhint %}

**Arguments**

| Argument                           | Type            | Required | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------------------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `quote`                            | boolean         | no       | Quote every request without reserving usage, creating canvas nodes, or starting generations. Requires generation\_quote API support; unsupported deployments fail closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `generations`                      | array of object | yes      | Independent generation requests. Use a one-item array for one generation. Each item accepts only the keys documented below — model-specific options go under params with names from flora\_list\_models; unknown top-level keys are rejected, not ignored. 1 to 20 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `generations[].workspace_id`       | string          | no       | Workspace to bill (ws\_…). Optional: resolved from project\_id when omitted. Can't be empty.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `generations[].project_id`         | string          | yes      | Project canvas to generate into (prj\_…). Use project\_id from flora\_list\_projects or flora\_create\_project. An API-issued canvas URL's /projects/\<id> segment becomes prj\_\<id>.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `generations[].type`               | string          | yes      | Output modality. One of `image`, `video`, `audio`, `text`, `model3d`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `generations[].prompt`             | string          | yes      | The generation prompt.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `generations[].model`              | string          | no       | Model id from flora\_list\_models.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `generations[].params`             | object          | no       | Model-specific parameters, with names from flora\_list\_models — the only place model options go. Do not pass them as top-level item keys.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `generations[].reference_node_ids` | array of string | no       | Canvas node UUIDs or short ids (n7 from flora\_get\_canvas / flora\_list\_canvas\_nodes (GET /projects/{projectId}/nodes) or a previous flora\_create\_generations response's node\_id) whose image or model3d outputs feed this generation. Wires an edge from each source node to the new node and attaches their outputs as the model's media inputs — use this instead of pasting URLs into params when the source already lives on the canvas. Read the media field name (image\_url, image\_urls, or model\_url) from flora\_list\_models. Works with image-to-image models (type=image) and model3d models that accept image or model3d inputs. A text-to-image id (t2i-\*) with references is routed to the same model's image-to-image / images-to-image shape when one exists; the response reports the model actually used. Image models with no image-input shape are rejected with input\_validation\_error. Model3D models must accept image or model3d inputs; video, audio, and text reference inputs remain unsupported. To animate a canvas image, add a video node wired to it with flora\_add\_to\_canvas and start it with flora\_run\_canvas\_nodes using the short id from the created map. Up to 20 items. Each item: 1 to 128 characters. |
| `generations[].add_to_canvas`      | boolean         | no       | Defaults to true: the generation gets a canvas node in project\_id. Set false to keep it off the canvas; its node\_id is then null, so it cannot be passed as reference\_node\_ids. Poll its run\_id with flora\_list\_generations as usual.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

Also takes the optional [skill attribution arguments](https://docs.flora.ai/mcp/tools.md#skill-attribution-arguments) `skill` and `skill_run_id`. Pass them when the agent is following a skill.

**Returns:** `{generations: [...]}` in input order, each with `index` and `ok`. Successes carry `run_id`, `canvas_url` and `node_id`; failures carry `error` and `status`. With `quote: true`, each entry is a cost estimate with no `run_id`. Give users `canvas_url`; never build project URLs from IDs.

**Cost:** Spends money for each successful item. Call it first with `quote: true` to price the exact requests without reserving money or starting anything, show the user the total in US dollars, and send the same request without `quote` after they approve. Never retry a whole batch after a partial failure: successful items already spent money, and a timeout may still have started a run.

**Usually comes after:** [`flora_list_models`](https://docs.flora.ai/mcp/tools/models-and-loras.md#flora_list_models), [`flora_list_projects`](https://docs.flora.ai/mcp/tools/workspaces-and-projects.md#flora_list_projects)

**Usually comes before:** [`flora_list_generations`](#flora_list_generations), [`flora_arrange_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_arrange_canvas)

**Example prompt:** "Make two 16:9 images of a red sneaker on wet asphalt in my Spring campaign project. Quote me first."

**Example call:**

```json
{
  "quote": true,
  "generations": [
    {
      "project_id": "prj_abc",
      "type": "image",
      "prompt": "Red sneaker on wet asphalt at dusk, low angle, reflections",
      "model": "t2i-gemini-3.1-flash-image",
      "params": {
        "aspect_ratio": "16:9"
      }
    },
    {
      "project_id": "prj_abc",
      "type": "image",
      "prompt": "Red sneaker on wet asphalt at dusk, overhead shot, puddles",
      "model": "t2i-gemini-3.1-flash-image",
      "params": {
        "aspect_ratio": "16:9"
      }
    }
  ]
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Start 1–20 independent generations concurrently. SPENDS USAGE for each successful submission unless quote=true: then return USD cost estimates for these exact requests, including assumptions and expiry, without reserving usage or starting generations. Quote entries have no run_id and must not be polled. Pass generations as an array, even for one item; each item supplies project_id, type, and prompt; workspace_id may be omitted to bill the workspace project_id belongs to. Returns {generations: [...]} in input order, each with index and ok. Successful entries include run_id, canvas_url, and node_id; failed entries include error and status when available. Save every successful run_id and poll flora_list_generations with run_ids. Never retry the whole batch after a partial failure: successful submissions already spend usage, and a timeout may have started a run — inspect history before retrying uncertain submissions. Pass reference_node_ids to use existing canvas nodes as image or model3d inputs. Works with image-to-image models (type=image) and model3d models that accept image or model3d inputs; video and other models are rejected with input_validation_error — to animate a canvas image, add a video node wired to it with flora_add_to_canvas and start it with flora_run_canvas_nodes using the short id from the created map. Text-to-image ids (t2i-*) with references route to the same model's image-to-image shape when one exists; otherwise they are rejected with input_validation_error. Media input field names (image_url vs image_urls, model_url) come from flora_list_models — use those names in params, or pass reference_node_ids instead of pasting URLs. Omit model to pick a default: image references use image-to-image or image-to-model3d. Model3D remesh/retexture (model3d sources) requires an explicit model from flora_list_models that declares model_url. Never build project URLs from ids; use canvas_url.
```

{% endcode %}

</details>

## flora\_list\_generations <a href="#flora_list_generations" id="flora_list_generations"></a>

Read up to 20 runs by `run_id` in one call, or list generation history with cost and outputs.

**Labels:** read-only

**Shown in clients as:** List generations

**Use when:** You're polling runs you started (with [`flora_create_generations`](#flora_create_generations), [`flora_run_canvas_nodes`](https://docs.flora.ai/mcp/tools/canvas.md#flora_run_canvas_nodes), [`flora_run_technique`](https://docs.flora.ai/mcp/tools/techniques-and-actions.md#flora_run_technique), [`flora_train_lora`](https://docs.flora.ai/mcp/tools/models-and-loras.md#flora_train_lora) or an action), or the user asks what was generated before.

**Don't use when:** You'd poll runs one at a time or faster than the polling rule allows: read every ID of a batch in one call and wait at least 15 seconds between polls. Pass only `run_…` IDs, never node IDs, asset IDs or quote entries.

**Arguments**

| Argument         | Type            | Required | Notes                                                                                                                                                                                                                                                                                                                        |
| ---------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run_ids`        | array of string | no       | Runs to read, at most 20; each is the run\_… id returned as run\_id by flora\_create\_generations or flora\_run\_technique (never a canvas node id, asset id or generation history entry). Omit this and the run\_id/runIds aliases to list history instead. Pass technique\_id alongside for technique runs. 1 to 20 items. |
| `run_id`         | string          | no       | Alias for reading one run: the same as run\_ids with a single entry. If several of run\_ids/run\_id/runIds are given, their ids are combined. Can't be empty.                                                                                                                                                                |
| `runIds`         | array of string | no       | camelCase alias for run\_ids; accepted for hosts that emit camelCase keys. If several of run\_ids/run\_id/runIds are given, their ids are combined. 1 to 20 items.                                                                                                                                                           |
| `technique_id`   | string          | no       | Technique the runs belong to (tech\_…); required for flora\_run\_technique runs, and applied to every id in the call.                                                                                                                                                                                                        |
| `workspace_id`   | string          | no       | Filter by workspace (ws\_…).                                                                                                                                                                                                                                                                                                 |
| `project_id`     | string          | no       | Filter by project (prj\_…). Use project\_id from flora\_list\_projects or flora\_create\_project. An API-issued canvas URL's /projects/\<id> segment becomes prj\_\<id>.                                                                                                                                                     |
| `status`         | string          | no       | Filter by run status. One of `pending`, `running`, `completed`, `failed`.                                                                                                                                                                                                                                                    |
| `include_inputs` | boolean         | no       | History listing only: include each generation's submitted inputs block — the prompt it executed (plus raw\_prompt when preprocessing rewrote it), wired canvas input elements, and reference asset ids. Off by default; the block can be large.                                                                              |
| `limit`          | number          | no       | Max items to return (default 20).                                                                                                                                                                                                                                                                                            |
| `cursor`         | string          | no       | Pagination cursor from a previous call's meta.next\_cursor.                                                                                                                                                                                                                                                                  |

Also takes the optional [skill attribution arguments](https://docs.flora.ai/mcp/tools.md#skill-attribution-arguments) `skill` and `skill_run_id`. Pass them when the agent is following a skill.

**Returns:** With `run_ids`: `{runs}`, one entry per ID with its status, cost and outputs, or an error entry (`ok: false`, `error`, `status`) for an ID it couldn't read. Without `run_ids`: a history page under `generations`, newest first, with cost and outputs, and `meta.next_cursor`.

**Cost:** Free. Polling too fast returns `429` entries or a cooldown error with `retry_after_seconds`.

**Usually comes after:** [`flora_create_generations`](#flora_create_generations), [`flora_run_canvas_nodes`](https://docs.flora.ai/mcp/tools/canvas.md#flora_run_canvas_nodes), [`flora_run_technique`](https://docs.flora.ai/mcp/tools/techniques-and-actions.md#flora_run_technique)

**Usually comes before:** [`flora_view_model3d`](#flora_view_model3d), [`flora_arrange_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_arrange_canvas)

**Example prompt:** "Check on the four images you just started."

**Example call:**

```json
{
  "run_ids": [
    "run_abc123",
    "run_abc124",
    "run_abc125",
    "run_abc126"
  ]
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Read specific generation runs or list history. Given run IDs, pass run_ids (an array even for one run); never substitute history or another run's result. Regular run IDs need no workspace or project lookup. For technique runs, also pass technique_id; flora_list_technique_runs lists history, not an exact run lookup. Read all IDs of a batch in one call, up to 20. Reading does not block: runs take tens of seconds, so wait between polls of the same batch — at least 15 seconds, and about 2 seconds per id for larger batches (40 seconds for 20) — because every id in run_ids is one API request against the workspace's per-minute rate limit, and faster polling returns status 429 error entries. Repeated or overlapping reads inside the poll interval receive a cooldown error with retry_after_seconds; no run payload is cached, so every returned run is freshly authorized by the API. A batch where every id is rate-limited or cooling down fails the whole call with retry_after_seconds. run_ids returns {runs}, with a separate error entry (ok:false, error, and status when the API answered) for each unreadable ID. Only omit run_ids when the user wants history; that returns the API page under generations, newest first, with cost and outputs. Pass include_inputs on a history read to also get each run's submitted prompt and input references. Past the tool-result size budget, long text fields come back as previews flagged inputs.truncated — narrow the page or read full text through the API (GET /generations?include_inputs=true) or SDK directly.
```

{% endcode %}

</details>

## flora\_view\_model3d <a href="#flora_view_model3d" id="flora_view_model3d"></a>

Open an interactive 3D viewer for a 3D run, with GLB links and preview images.

**Labels:** read-only

**Shown in clients as:** View 3D model

**Use when:** A 3D generation finished and the user wants to inspect it, or you need its `asset_id` to chain it into another step.

**Don't use when:** You want to judge how the model looks from the user's viewer: you can only evaluate the provider preview images this returns. Never paste GLB bytes into a reply.

**Arguments**

| Argument       | Type   | Required | Notes                                                            |
| -------------- | ------ | -------- | ---------------------------------------------------------------- |
| `run_id`       | string | yes      | Run to inspect (run\_…). Can't be empty.                         |
| `technique_id` | string | no       | Technique owning the run (tech\_…); required for technique runs. |

**Returns:** The run's `asset_id`, GLB links, and up to three provider preview images when available. No previews means the visual quality is unknown. Pending runs can be refreshed.

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_list_generations`](#flora_list_generations)

**Usually comes before:** [`flora_create_generations`](#flora_create_generations)

**Example prompt:** "Show me the 3D model from that run."

**Example call:**

```json
{
  "run_id": "run_abc123"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Open an interactive 3D viewer for a run from flora_list_generations. Read-only and credit-free: orbit, pan, zoom, reset, inspect metadata, or open the GLB. Supply technique_id for technique runs. Returns asset_id and GLB links for chaining without geometry bytes, plus up to three provider preview images when available. The model can evaluate only those image blocks, not the user's interactive view; no previews means visual quality is unknown. Pending runs can be refreshed. Never inline a GLB.
```

{% endcode %}

</details>


---

# 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/tools/generations.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.
