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

# Generate an image or video

Ask your agent to generate images, video, 3D, audio or text with FLORA MCP, with or without reference images, with a model names to IDs table (Nano Banana, Kling, Veo, Sora, Seedance, WAN, Runway) and

Ask your agent for an image, a video, a 3D model, audio or text, and [FLORA MCP](https://flora.ai/mcp) runs the model and puts the result on a project canvas. Use this recipe for one-off work of up to 20 generations. For a list of products or variants, use [Batch-generate 20 to 500 assets](https://docs.flora.ai/mcp/recipes/batch.md). For a saved multi-step workflow, use [Run your team's Technique](https://docs.flora.ai/mcp/recipes/run-a-technique.md).

**Works in:** Claude · Claude Code · ChatGPT · Codex · Cursor

**You need:** a connected client, a workspace, about $0.07 per image (Nano Banana 2 at 1K) or about $0.71 per 5-second video (Kling 3.0 Pro at 1080p)

**Use when:** you want a few images or clips from a prompt, from images already on a canvas, or from a photo URL.

**Don't use when:** you have a long list to work through (use [batch](https://docs.flora.ai/mcp/recipes/batch.md)), your team already saved the workflow as a Technique (use [run a Technique](https://docs.flora.ai/mcp/recipes/run-a-technique.md)), or you want to animate an image that already sits on a canvas (use [image to video](https://docs.flora.ai/mcp/recipes/image-to-video.md)).

## Ask your agent

> Use FLORA to make 3 product shots of a matte black ceramic mug on a sunlit oak table, 4:5, in my "Mug launch" project. Show me the cost first and wait for my OK before generating.

<a href="https://claude.ai/new?q=Use%20FLORA%20to%20make%203%20product%20shots%20of%20a%20matte%20black%20ceramic%20mug%20on%20a%20sunlit%20oak%20table%2C%204%3A5%2C%20in%20my%20%22Mug%20launch%22%20project.%20Show%20me%20the%20cost%20first%20and%20wait%20for%20my%20OK%20before%20generating." class="button primary">Open in Claude</a> <a href="https://chatgpt.com/?q=Use%20FLORA%20to%20make%203%20product%20shots%20of%20a%20matte%20black%20ceramic%20mug%20on%20a%20sunlit%20oak%20table%2C%204%3A5%2C%20in%20my%20%22Mug%20launch%22%20project.%20Show%20me%20the%20cost%20first%20and%20wait%20for%20my%20OK%20before%20generating." class="button secondary">Open in ChatGPT</a>

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

### Find the workspace and project

Every generation is billed to a workspace and lands on a project canvas. The agent calls `flora_list_workspaces`. If it returns `current_workspace_id`, that is the workspace you're in. If several workspaces come back and none is current, the agent names them and asks which one to bill.

Then it finds the project with `flora_list_projects`, or creates one with `flora_create_project`:

```json
{
  "workspace_id": "ws_123",
  "name": "Mug launch"
}
```

Either way it gets the `project_id` (for example `prj_abc`) used below.
{% endstep %}

{% step %}

### Pick a model and read its parameters

The agent calls `flora_list_models` with `type` to see what's available, then once with `model_id` to get that model's exact parameter names and allowed values:

```json
{
  "model_id": "t2i-gemini-3.1-flash-image"
}
```

The response lists every `params` entry, for example `aspect_ratio` (`"1:1"`, `"4:5"`, `"16:9"`, …), `resolution` (`"1K"`, `"2K"`, `"4K"`) and `seed`, plus `estimated_cost_usd` and `estimated_seconds` at default settings. See [Choose a model](#choose-a-model) below.
{% endstep %}

{% step %}

### Quote the cost and wait for approval

The agent sends the exact request with `quote: true`. Nothing runs and nothing is charged.

```json
{
  "quote": true,
  "generations": [
    {
      "project_id": "prj_abc",
      "type": "image",
      "prompt": "Studio product photo of a matte black ceramic mug on a sunlit oak table, soft morning light from the left, shallow depth of field",
      "model": "t2i-gemini-3.1-flash-image",
      "params": { "aspect_ratio": "4:5", "resolution": "1K" }
    }
  ]
}
```

Each quote entry carries `model.model_id`, `estimated_cost` in US dollars and `expires_at`. Quote entries have no `run_id`. The agent shows you the total and waits for your OK.
{% endstep %}

{% step %}

### Start the generations

The agent sends the same request without `quote`. `generations` is always an array, even for one item, and takes up to 20 items. Each item is independent, so three images are three items:

```json
{
  "generations": [
    {
      "project_id": "prj_abc",
      "type": "image",
      "prompt": "Studio product photo of a matte black ceramic mug on a sunlit oak table, soft morning light from the left, shallow depth of field",
      "model": "t2i-gemini-3.1-flash-image",
      "params": { "aspect_ratio": "4:5", "resolution": "1K" }
    },
    {
      "project_id": "prj_abc",
      "type": "image",
      "prompt": "Overhead product photo of a matte black ceramic mug on a sunlit oak table, latte art, morning light",
      "model": "t2i-gemini-3.1-flash-image",
      "params": { "aspect_ratio": "4:5", "resolution": "1K" }
    },
    {
      "project_id": "prj_abc",
      "type": "image",
      "prompt": "Close-up product photo of a matte black ceramic mug handle on a sunlit oak table, warm light, shallow depth of field",
      "model": "t2i-gemini-3.1-flash-image",
      "params": { "aspect_ratio": "4:5", "resolution": "1K" }
    }
  ]
}
```

The response returns one entry per item, in input order (the first of three shown):

```json
{
  "generations": [
    {
      "index": 0,
      "ok": true,
      "run_id": "run_a1",
      "type": "generation",
      "model": { "model_id": "t2i-gemini-3.1-flash-image" },
      "estimated_seconds": 65,
      "charged_cost": 0.072,
      "project_id": "prj_abc",
      "canvas_url": "https://app.flora.ai/projects/…",
      "poll_url": "https://app.flora.ai/api/v1/runs/run_a1",
      "node_id": "7f6ae6da-4a0e-4a2f-9c6a-2c1c6b8d1f21"
    }
  ]
}
```

`charged_cost` is the estimated cost in US dollars, and `estimated_seconds` is a good hint for when to make the first poll on slow models. The agent saves every `run_id` and `node_id`. A failed item has `ok: false`, an `error` and usually a `status`. It never cancels the items that started.
{% endstep %}

{% step %}

### Poll until the runs finish

The agent follows the polling rule above and reads every `run_id` in one call:

```json
{
  "run_ids": ["run_a1", "run_b2", "run_c3"]
}
```

`flora_list_generations` returns `{ "runs": [...] }`. A run is done when `status` is `completed` (its `outputs[].url` holds the media) or `failed` (it carries `error_code` and `error_message`). Images usually take under two minutes. Video takes several minutes, so for video the agent can wait 30 to 60 seconds between polls.
{% endstep %}

{% step %}

### Hand you the results

The agent shares the output URLs and the `canvas_url` from the create response. It never builds a canvas link from a project ID.
{% endstep %}
{% endstepper %}

## Choose a model

Two ways to choose:

* **Omit `model`.** FLORA picks its current default for the `type`. With `reference_node_ids` on an image or 3D request, it picks an image-to-image or image-to-3D default instead. The quote and the create response name the model they used in `model.model_id`, so you always know what ran. Defaults can change, so pass `model` when you need a specific one.
* **Pass `model`** with an ID from `flora_list_models`. Use only the `params` names and values that `flora_list_models` returns for that ID. Unknown top-level keys on an item are rejected, and model options go under `params`, never beside it.

Recommended starting models per job. These are suggestions to pass as `model`, not FLORA's defaults. Prices are at each model's default settings, from [Model Pricing](https://docs.flora.ai/plans-and-billing/model-pricing.md):

| Job                           | `type`    | `model`                                                                      | Key `params`                                                            | About         | Model page                                                                                |
| ----------------------------- | --------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------- |
| Image from text               | `image`   | `t2i-gemini-3.1-flash-image` (Nano Banana 2)                                 | `aspect_ratio`, `resolution`, `seed`                                    | $0.07         | [Nano Banana 2](https://docs.flora.ai/models/image-models/nano-banana-2-by-google.md)     |
| Image from one reference      | `image`   | `i2i-gemini-3.1-flash-image`                                                 | `image_url`, `aspect_ratio`, `resolution`                               | $0.07         | [Nano Banana 2](https://docs.flora.ai/models/image-models/nano-banana-2-by-google.md)     |
| Image from several references | `image`   | `is2i-gemini-3.1-flash-image`                                                | `image_urls`, `aspect_ratio`, `resolution`                              | $0.07         | [Nano Banana 2](https://docs.flora.ai/models/image-models/nano-banana-2-by-google.md)     |
| Premium image                 | `image`   | `t2i-gemini-3-pro` (Nano Banana Pro)                                         | `aspect_ratio`, `resolution`, `seed`                                    | $0.18         | [Nano Banana Pro](https://docs.flora.ai/models/image-models/nano-banana-pro-by-google.md) |
| Video from text               | `video`   | `t2v-kling-v3-pro` (Kling 3.0 Pro)                                           | `aspect_ratio`, `resolution`, `duration`                                | $0.71 for 5 s | [Kling 3.0 Pro](https://docs.flora.ai/models/video-models/kling-3.0-pro-by-kuaishou.md)   |
| Video from a photo            | `video`   | `i2v-kling-v3-pro`                                                           | `image_url`, `resolution`, `duration`                                   | $0.71 for 5 s | [Kling 3.0 Pro](https://docs.flora.ai/models/video-models/kling-3.0-pro-by-kuaishou.md)   |
| Fast video                    | `video`   | `t2v-minimax-h3-max-gateway` / `i2v-minimax-h3-max-gateway` (MiniMax H3 Max) | `duration`, `resolution`, `aspect_ratio` (`i2v`: `image_url`, required) | $0.48 for 5 s | [MiniMax H3](https://docs.flora.ai/models/video-models/minimax-h3-by-minimax.md)          |
| 3D from text                  | `model3d` | `t3d-hunyuan3d-v3-t3d` (Hunyuan3D v3.1 Rapid)                                | none                                                                    | $0.27         | [3D models](https://docs.flora.ai/models/3d-models.md)                                    |
| 3D from an image              | `model3d` | `i3d-trellis-2` (Trellis 2)                                                  | `image_url`, `resolution`                                               | $0.36         | [3D models](https://docs.flora.ai/models/3d-models.md)                                    |
| Voice-over                    | `audio`   | `t2a-elevenlabs-v4-t2a` (Eleven v4)                                          | `voice_id`, `stability`                                                 | $0.05         | [Audio models](https://docs.flora.ai/models/audio-models.md)                              |
| Copy or a prompt              | `text`    | `t2t-claude-opus-5-5` (Claude Opus 5.5)                                      | none                                                                    | $0.01         | [Text models](https://docs.flora.ai/models/text-models.md)                                |

Video `duration` values are strings (`"5"`, not `5`). Longer clips and higher resolutions cost more; the quote always reflects the exact `params`.

{% hint style="info" %}
The catalog changes often. `flora_list_models` is the source of truth for IDs, parameters and estimated prices on your account. Models FLORA features come first in its response, under `featured`.
{% endhint %}

### Model names to IDs

People ask for models by name; the tools need the `model` ID. A name usually has one ID per input shape, and IDs don't always match the name: **Nano Banana 2 is `t2i-gemini-3.1-flash-image`**, and Nano Banana 2.1 is `t2i-elote-gateway`. Prices are at default settings, from [Model Pricing](https://docs.flora.ai/plans-and-billing/model-pricing.md).

**Nano Banana (image)**

| Name               | From text                                  | From one image (`image_url`)               | From several images (`image_urls`)           | About  |
| ------------------ | ------------------------------------------ | ------------------------------------------ | -------------------------------------------- | ------ |
| Nano Banana        | `t2i-nano-banana`                          | `i2i-nano-banana`                          | `is2i-nano-banana`                           | $0.047 |
| Nano Banana 2      | `t2i-gemini-3.1-flash-image`               | `i2i-gemini-3.1-flash-image`               | `is2i-gemini-3.1-flash-image`                | $0.072 |
| Nano Banana 2 Lite | `t2i-nano-banana-2-lite-t2i-google-gemini` | `i2i-nano-banana-2-lite-i2i-google-gemini` | `is2i-nano-banana-2-lite-is2i-google-gemini` | $0.043 |
| Nano Banana 2.1    | `t2i-elote-gateway`                        | `i2i-elote-gateway`                        | `is2i-elote-gateway`                         | $0.035 |
| Nano Banana Pro    | `t2i-gemini-3-pro`                         | `i2i-gemini-3-pro`                         | `is2i-gemini-3-pro`                          | $0.18  |

**Kling and other video**

| Name                       | From text                          | From an image (`image_url`)        | About (default settings, usually 5 s) |
| -------------------------- | ---------------------------------- | ---------------------------------- | ------------------------------------- |
| Kling 3.0 Pro              | `t2v-kling-v3-pro`                 | `i2v-kling-v3-pro`                 | $0.71                                 |
| Kling 3.0 Pro (Turbo)      | `t2v-kling-3-0-pro-turbo-t2v`      | `i2v-kling-3-0-pro-turbo-i2v`      | $0.84                                 |
| Kling 3.0 Standard         | `t2v-kling-v3-standard`            | `i2v-kling-v3-standard`            | $0.53                                 |
| Kling 3.0 Standard (Turbo) | `t2v-kling-3-0-standard-turbo-t2v` | `i2v-kling-3-0-standard-turbo-i2v` | $0.67                                 |
| Kling O3 Pro               | `t2v-kling-o3`                     | `i2v-kling-o3`                     | $0.59                                 |
| Kling O3 Standard          | `t2v-kling-o3-standard`            | `i2v-kling-o3-standard`            | $0.47                                 |
| Kling O1                   | `t2v-kling-o1`                     | `i2v-kling-o1`                     | $0.47                                 |
| Kling 2.6 Pro              | `t2v-kling-2.6`                    | `i2v-kling-2.6`                    | $0.68                                 |
| Kling 2.5 Turbo Pro        | `t2v-kling-2.5`                    | `i2v-kling-2.5`                    | $0.29                                 |
| Kling 2.1 Master           | `t2v-kling-2.1`                    | `i2v-kling-2.1`                    | $1.38                                 |
| Kling 2.0 Master           | `t2v-kling-2.0`                    | `i2v-kling-2.0`                    | $1.38                                 |
| Kling Pro 1.6              | `t2v-kling-pro-1.6`                | `i2v-kling-pro-1.6`                | $0.33                                 |
| MiniMax H3 Max             | `t2v-minimax-h3-max-gateway`       | `i2v-minimax-h3-max-gateway`       | $0.48                                 |
| Veo 3.1                    | `t2v-veo3.1`                       | `i2v-veo3.1`                       | $3.84 (720p, 8 s)                     |
| Veo 3.1 (Fast)             | `t2v-veo3.1-fast`                  | `i2v-veo3.1-fast`                  | $1.44 (720p, 8 s)                     |
| Veo 3.1 Lite               | `t2v-veo-3-1-lite-t2v`             | `i2v-veo-3-1-lite-i2v`             | $0.48 (8 s)                           |
| Sora 2 Pro                 | `t2v-sora2-pro`                    | `i2v-sora2-pro`                    | $1.44 (720p, 4 s)                     |
| Seedance 2.5               | `t2v-gengateway-seedance-2-5-t2v`  | `i2v-gengateway-seedance-2-5-i2v`  | $2.48 (720p)                          |
| Seedance 2.0               | `t2v-seedance-2.0-enhancor`        | `i2v-seedance-2.0-enhancor`        | $1.06 (720p)                          |
| Seedance 2.0 Fast          | `t2v-seedance-2.0-fast-enhancor`   | `i2v-seedance-2-fast-enhancor`     | $0.85 (720p)                          |
| Seedance 1.5 Pro           | `t2v-seedance-1.5-pro`             | `i2v-seedance-1.5-pro`             | $0.31 (720p)                          |
| WAN 3.0                    | `t2v-wan-3-0-gateway`              | `i2v-wan-3-0-gateway`              | $0.60 (720p)                          |
| Runway Gen-4.5             | `t2v-runway-gen-4.5`               | `i2v-runway-gen-4.5`               | $0.72                                 |

"Kling" with no version means Kling 3.0 Pro in these recipes. `duration` values differ by model: most take plain seconds (`"5"`), but Veo takes `"4s"`, `"6s"` or `"8s"`, so copy them from `flora_list_models`. The 3D, audio and text starting models are in the table above.

This is a subset. For every live ID behind a name, call `flora_list_models` with `query`, for example `{ "query": "kling" }`. That also returns the variants not listed here, such as first and last frame (`f2v-`), multi-reference (`r2v-`), video edit (`v2v-`) and motion control (`iv2v-`) models. Then call it again with `model_id` for that model's `params`.

## Generate from reference images

Most image work starts from a reference: a product shot, a sketch, a previous result. There are two ways to pass one.

**From the canvas (preferred).** Pass `reference_node_ids` with node IDs: the `node_id` from an earlier `flora_create_generations` response, a short ID like `n7` from `flora_get_canvas`, or an uploaded file's node (it lands on the canvas when you upload with `project_id`; see [Upload your own images, video and files](https://docs.flora.ai/mcp/recipes/upload-files.md#use-what-you-uploaded)). FLORA wires an edge from each source node to the new one and feeds their outputs to the model. Up to 20 references per item.

```json
{
  "generations": [
    {
      "project_id": "prj_abc",
      "type": "image",
      "prompt": "The same mug on a white marble counter next to a croissant, bright morning light",
      "model": "i2i-gemini-3.1-flash-image",
      "params": { "aspect_ratio": "4:5" },
      "reference_node_ids": ["n7"]
    }
  ]
}
```

With references, a text-to-image ID such as `t2i-gemini-3.1-flash-image` routes to the same model's image-to-image version when one exists, and the response reports the model actually used.

**From a URL.** Put a public HTTPS image URL in the image field `flora_list_models` names for that model. One-image models use `image_url`; multi-image models use `image_urls` (an array):

```json
{
  "generations": [
    {
      "project_id": "prj_abc",
      "type": "image",
      "prompt": "Combine the mug from image 1 with the table setting from image 2, warm light",
      "model": "is2i-gemini-3.1-flash-image",
      "params": {
        "image_urls": [
          "https://media.flora.ai/…/mug.png",
          "https://media.flora.ai/…/table.png"
        ]
      }
    }
  ]
}
```

The URL must serve the image file itself, not a web page. Files you share in Claude or ChatGPT already have a hosted URL. For a file on your computer, see [Upload your own images, video and files](https://docs.flora.ai/mcp/recipes/upload-files.md).

`reference_node_ids` works for image models and for 3D models that take an image or 3D input. Video, audio and text models reject canvas references with an `input_validation_error` (HTTP 400). To animate an image, see [Turn a product photo into video](https://docs.flora.ai/mcp/recipes/image-to-video.md).

## Video, 3D, audio and text

* **Video from text:** `type: "video"` with a text-to-video model. Video takes minutes, not seconds: most video models take 2 to 5 minutes, and the slowest take up to about 26 minutes. Read `estimated_seconds` in `flora_list_models` for the model you picked (Kling 3.0 Pro estimates about 4 to 5 minutes).
* **Video from a photo:** pass the photo URL in the model's `image_url`. The full recipe, including animating an image already on a canvas, is in [Turn a product photo into video](https://docs.flora.ai/mcp/recipes/image-to-video.md).
* **3D:** `type: "model3d"`. From text, use a `t3d-` model. From an image, pass `reference_node_ids` or the image URL in `image_url`. Remeshing or retexturing an existing 3D model needs an explicit `m3d2m3d-` model that declares `model_url`. Inspect a finished model with `flora_view_model3d` and its `run_id`; it's read-only and free.
* **Audio:** `type: "audio"` with a text-to-audio model. The prompt is the script or sound description.
* **Text:** `type: "text"` with a text model, for copy, captions or prompts to feed the next step.

## Check it worked

* Every item in the create response has `ok: true` and a `run_id`.
* `flora_list_generations` with those `run_ids` shows `status: "completed"` and an `outputs[].url` for each.
* The canvas at `canvas_url` shows one new node per generation, with references wired in.

## If it fails

| Symptom                                              | Cause                                                                                                | Fix                                                                                                                                   |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `input_validation_error` with `reference_node_ids`   | The model is a video, audio or text model, or an image model with no image input                     | Use an image-to-image or image-to-3D model. To animate, follow [image to video](https://docs.flora.ai/mcp/recipes/image-to-video.md). |
| `input_validation_error` naming a key                | A model option was passed beside `prompt` instead of inside `params`, or the key isn't in the schema | Move it under `params`, using names from `flora_list_models`.                                                                         |
| Error lists available model IDs                      | The `model` ID doesn't exist on this account                                                         | Pick one from `flora_list_models` with the same `type`.                                                                               |
| Output has the wrong size or ratio                   | A `params` value wasn't one the model accepts, so it fell back to a default                          | Copy values exactly from `flora_list_models` (for example `"4:5"`, `"1K"`).                                                           |
| `insufficient_credits` or a `BILLING_*` code         | Not enough balance in the workspace                                                                  | Stop and relay the message. Don't retry. See [cost and limits](https://docs.flora.ai/mcp/cost-and-limits.md).                         |
| `paid_plan_required` (HTTP 403)                      | The workspace's plan doesn't include what you asked for. Adding balance doesn't fix it               | Relay the message. Use a workspace whose plan includes it, ask the owner to change plans, or generate another type.                   |
| `429` entries or `retry_after_seconds` while polling | Polling faster than the poll rule                                                                    | Wait the stated seconds, then poll the whole batch in one call.                                                                       |
| Run `failed` with `GENERATION_PROMPT_MODERATED`      | The prompt or reference was blocked                                                                  | Change the prompt or reference. Retrying it unchanged fails the same way.                                                             |
| The create call timed out                            | The run may have started anyway                                                                      | Read history with `flora_list_generations` (no `run_ids`, filter by `project_id`) before you try again.                               |

More error codes and the stuck-run rule are in [FLORA MCP runs: polling, timeouts and failures](https://docs.flora.ai/mcp/runs.md). Every argument is in the [tools reference](https://docs.flora.ai/mcp/tools/generations.md#flora_create_generations).


---

# 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/generate.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.
