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

# Generations

Start a one-off image, video, audio, text or 3D generation with the FLORA API, price it first with a quote, and read the result.

A generation runs one model directly, with no saved Technique. Pass a `type`, a `prompt`, the workspace that pays and the project it lands in, plus an optional model ID and parameters; FLORA starts the run, puts it on the project's canvas as a node, and returns a `run_id` to poll.

For a repeatable workflow with fixed inputs and several steps, build a [Technique](/api/guides/techniques.md) instead. To train your own style, see [Train and use LoRA Styles](/api/guides/loras.md).

## Price it first

Pass `quote: true` to get an estimate for the exact request without starting anything or reserving money:

```bash
curl -X POST https://app.flora.ai/api/v1/generate \
  -H "Authorization: Bearer $FLORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quote": true,
    "type": "image",
    "prompt": "A cinematic product photo of a ceramic mug on a sunlit table",
    "workspace_id": "ws_abc123",
    "project_id": "prj_abc123",
    "model": "t2i-flux-2-pro"
  }'
```

The response has `estimated_cost` in US dollars, the `assumptions` behind it, and an `expires_at` five minutes out. A quote is an estimate, not a price lock or a balance check. If the model would refuse the inputs (for example, a reference video that is too short), the quote fails with `400 input_validation_error` and the reason.

{% hint style="warning" %}
Calling the API directly? Check that the deployment supports quotes before you rely on them: `GET https://app.flora.ai/api/meta/release` lists `generation_quote` in `publicApiFeatures`. An API without it ignores `quote` and starts the generation. The TypeScript SDK checks this for you.
{% endhint %}

## Start a generation

{% tabs %}
{% tab title="curl" %}

```bash
curl -X POST https://app.flora.ai/api/v1/generate \
  -H "Authorization: Bearer $FLORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "prompt": "A cinematic product photo of a ceramic mug on a sunlit table",
    "workspace_id": "ws_abc123",
    "project_id": "prj_abc123",
    "model": "t2i-flux-2-pro",
    "params": { "aspect_ratio": "landscape_16_9" }
  }'
```

{% endtab %}

{% tab title="TypeScript" %}

```ts
import { FloraClient } from "@flora-ai/flora"

const client = new FloraClient()

const request = {
  type: "image",
  prompt: "A cinematic product photo of a ceramic mug on a sunlit table",
  workspace_id: "ws_abc123",
  project_id: "prj_abc123",
  model: "t2i-flux-2-pro",
  params: { aspect_ratio: "landscape_16_9" },
} as const

const quote = await client.generations.create({ ...request, quote: true })
console.log(`About $${quote.estimated_cost}`)

const run = await client.generations.create(request)
console.log(run.run_id, run.canvas_url)
```

{% endtab %}
{% endtabs %}

Response (`201 Created`):

```json
{
  "run_id": "run_abc123",
  "type": "generation",
  "estimated_seconds": 30,
  "charged_cost": 0.036,
  "poll_url": "https://app.flora.ai/api/v1/runs/run_abc123",
  "model": { "model_id": "t2i-flux-2-pro" },
  "project_id": "prj_abc123",
  "canvas_url": "https://app.flora.ai/projects/...",
  "node_id": "..."
}
```

`charged_cost` is in US dollars: the list price of this exact request, before any plan discount, so treat it as an estimate. The settled cost is on the run once it finishes ([Poll for the result](#poll-for-the-result)). `canvas_url` opens the project with the new node; use it as returned rather than building project URLs yourself.

## Request fields

| Field                | Required | Notes                                                                                                                                                                                     |
| -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`               | Yes      | `image`, `video`, `audio`, `text` or `model3d`. Model families like `t2i`, `i2v` or `text-to-image` aren't types                                                                          |
| `prompt`             | Yes      | What to generate                                                                                                                                                                          |
| `workspace_id`       | Yes      | The workspace that pays. A `ws_` ID from `GET /workspaces`                                                                                                                                |
| `project_id`         | Yes      | The project whose canvas the result lands on. A `prj_` ID from `GET /projects`                                                                                                            |
| `model`              | No       | A model ID from `GET /models`, for example `t2i-flux-2-pro`. Not a display name. If omitted, FLORA picks the default for the type                                                         |
| `params`             | No       | Model parameters, such as `aspect_ratio` or `seed`. Each model's accepted names and values are in its `params` from `GET /models`                                                         |
| `reference_node_ids` | No       | Canvas nodes in the same project whose outputs feed this generation as image (or 3D) inputs. Video and audio nodes are rejected                                                           |
| `callback_url`       | No       | An HTTPS URL that gets a signed callback when the run finishes. See [Webhooks](/api/platform/webhooks.md)                                                                                 |
| `quote`              | No       | `true` returns an estimate and starts nothing                                                                                                                                             |
| `add_to_canvas`      | No       | Defaults to `true`. Set `false` to keep the run off the canvas: `node_id` comes back `null`, so you can't pass the run in `reference_node_ids`. Read its outputs from `GET /runs/{runId}` |

To retry safely after a network error, send an `Idempotency-Key` header. See [Idempotency](/api/platform/idempotency.md).

## Use your own images

Image-to-image and image-to-video models take a picture as a parameter. Look up the parameter name in the model's `params` from `GET /models` (for example `image_url` or `image_urls`) and pass a public `https://` URL there, ideally a FLORA [asset](/api/guides/assets.md) URL. To build on something already on the canvas, pass its node in `reference_node_ids` instead.

## Poll for the result

Read the run at its `poll_url` (`GET /runs/{runId}`) until `status` is `completed` or `failed`. Each poll counts against your workspace's rate limit, so wait about 15 seconds between polls; video usually takes several minutes. Or skip polling with a [webhook](/api/platform/webhooks.md).

{% tabs %}
{% tab title="curl" %}

```bash
curl https://app.flora.ai/api/v1/runs/run_abc123 \
  -H "Authorization: Bearer $FLORA_API_KEY"
```

{% endtab %}

{% tab title="TypeScript" %}

```ts
let result = await client.generations.retrieve({ runId: run.run_id })
while (result.status === "pending" || result.status === "running") {
  await new Promise((resolve) => setTimeout(resolve, 15_000))
  result = await client.generations.retrieve({ runId: run.run_id })
}
console.log(result.status, result.outputs?.map((output) => output.url))
```

{% endtab %}
{% endtabs %}

A completed run has `outputs[].url`. A failed run has `error_code` and `error_message`; see [Errors](/api/platform/errors.md#run-failures).

In workspaces with [IP risk checks](/legal/data-security-and-ip.md#ip-risk-checks-enterprise), the primary output also carries `ip_risk`. The check runs after the generation finishes, so it starts as `{ "status": "pending" }`. When it's done, `status` is `completed` with a `level` (`High` at 85+, `Medium` at 60+, otherwise `Low`), a `score` from 0 to 100, and the `matches` it found, each with a `name` and a `similarity` from 0 to 1. If the check can't run, `status` is `error` with an `error_kind`. In other workspaces, and on outputs that weren't checked, `ip_risk` is absent rather than `null`. `GET /generations` returns the same field. `GET /generations` lists your recent generations, newest first, filtered by `workspace_id`, `project_id` or `status`.

## Common endpoints

| Method | Path                 | Description                                                                  |
| ------ | -------------------- | ---------------------------------------------------------------------------- |
| GET    | `/models?type=image` | [Find model IDs, parameters and prices](/api/reference/models/listmodels.md) |
| POST   | `/generate`          | [Quote or start a generation](/api/reference/generations/startgeneration.md) |
| GET    | `/runs/{runId}`      | [Read a run's status and outputs](/api/reference/runs/getrun.md)             |
| GET    | `/generations`       | [List recent generations](/api/reference/generations/listgenerations.md)     |

## Common validation issues

* `type` must be exactly `image`, `video`, `audio`, `text` or `model3d`.
* `model` must be an ID string from `GET /models`. If you see `Model "..." is not available`, list models for the same `type` and use one of the returned IDs.
* `workspace_id` and `project_id` are required and must use the `ws_` and `prj_` prefixes.

## Notes

* Output URLs are long-lived but not permanent. Download anything you need to keep.
* Generating from an AI client? FLORA MCP's `flora_create_generations` starts up to 20 at once; see [Generate an image or video](/mcp/recipes/generate.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/api/guides/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.
