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

# Start a generation

Start a generation with the FLORA API: POST /generate.

With quote=true, returns an estimate for the prepared request without reserving credits, creating a node, or starting a generation. Quotes expire after five minutes and do not lock pricing or guarantee admission. Otherwise starts a model generation using type, prompt, workspace\_id, project\_id, optional model endpoint ID, optional model parameters, and optional reference\_node\_ids (canvas node UUIDs used as image or model3d inputs; the new node is wired to them with edges). Use type=image|video|audio|text|model3d and model IDs returned by GET /models or list\_models. The response includes node\_id for the created canvas node, or null when add\_to\_canvas is false. Poll the returned run\_id via GET /runs/{runId} for progress and outputs. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency\_duplicate.

```http
POST https://app.flora.ai/api/v1/generate
```

* **Auth:** API key as a bearer token, `Authorization: Bearer $FLORA_API_KEY`. See [Authentication](https://docs.flora.ai/api/platform/authentication.md).
* **TypeScript SDK:** `client.generations.create()`.
* **Idempotency:** optional `Idempotency-Key` header. See [Idempotency](https://docs.flora.ai/api/platform/idempotency.md).
* **Operation ID:** `startGeneration`.

## Example

{% 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"
}'
```

{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
import { FloraClient } from '@flora-ai/flora';

const client = new FloraClient({ apiKey: process.env['FLORA_API_KEY'] });

const generation = await client.generations.create({
  type: 'image',
  prompt: 'A cinematic product photo of a ceramic mug on a sunlit table',
  workspace_id: 'ws_abc123',
  project_id: 'prj_abc123',
});
console.log(generation);
```

{% endtab %}
{% endtabs %}

## Request body

Required.

| Field                | Type            | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `quote`              | boolean         | No       | Return a quote without starting a generation or reserving credits. Requires the generation\_quote API capability.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `type`               | string          | Yes      | Generation type. Use "image", "video", "audio", "text", or "model3d"; do not pass model families such as "t2i" or "i2v". One of: `image`, `video`, `audio`, `text`, `model3d`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `prompt`             | string          | Yes      | Generation prompt. At least 1 character. Example: `A cinematic product photo of a ceramic mug on a sunlit table`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `model`              | string          | No       | Model endpoint ID, not a display name. Use list\_models (or GET /models) to find accessible endpoint IDs for the requested type. Example: `t2i-flux-2-pro`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `workspace_id`       | string          | Yes      | Workspace identifier. Use the public API ID returned by list workspaces; it must start with ws\_. Example: `ws_abc123`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `project_id`         | string          | Yes      | Project identifier. Use the public API ID returned by list projects; it must start with prj\_. Example: `prj_abc123`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `params`             | object          | No       | Model parameters                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `reference_node_ids` | array of string | No       | Canvas node UUIDs or short ids (n7, as returned by flora\_get\_canvas) whose outputs feed this generation as media inputs. For type=image this is image-to-image chaining (completed image outputs). For type=model3d this accepts image, model3d, or video sources when the model declares the corresponding input. Each node must be in project\_id; use the node\_id values from GET /projects/{projectId}/nodes (flora\_list\_canvas\_nodes) or a previous generation's node\_id. The server resolves their URLs, attaches them as the model's declared media inputs (image\_url, image\_urls, model\_url, or video\_url — see GET /models), and draws an edge from each source node to the new node. Audio sources are rejected with input\_validation\_error. Video references require an explicit model3d model with a video\_url input. A text-to-image model id with references routes to the same model's image-input sibling when exactly one exists; absent or ambiguous siblings keep the normal input\_validation\_error rejection. The response reports the model actually used. `@[nodeId]` markers in prompt are unioned into this list automatically. At most 20 items. Example: `["7f6ae6da-4a0e-4a2f-9c6a-2c1c6b8d1f21"]`. |
| `add_to_canvas`      | boolean         | No       | Create a canvas node in project\_id for this generation and attach its output there. Defaults to true. Set false to keep the run off the canvas: the response's node\_id is then null, so the run cannot be passed as reference\_node\_ids; read its outputs from GET /runs/{runId}. Default: `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `callback_url`       | string (uri)    | No       | HTTPS URL that receives a signed POST webhook when the run reaches a terminal state (events run.completed / run.failed). The JSON body is HMAC-SHA256 signed via the Flora-Signature header and delivery is retried up to 3 times with exponential backoff. Must be HTTPS and must not resolve to a private/internal host. See <https://docs.flora.ai/api/platform/webhooks> for the payload schema and verification example.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

## Responses

### 200: Generation started, or a read-only quote returned.

The body takes one of 2 shapes, set by `type`.

**Shape 1: `type` is `generation`, `technique` or `action`.**

| Field                    | Type                 | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------ | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run_id`                 | string               | Yes      | Run identifier. Pattern: `^run_\S+$`. Example: `run_abc123`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `type`                   | string               | Yes      | Run type. One of: `generation`, `technique`, `action`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `model`                  | object or null       | No       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `model.model_id`         | string               | Yes      | Model identifier. At least 1 character. Example: `t2i-flux-2-pro`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `technique`              | object or null       | No       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `technique.technique_id` | string               | Yes      | Technique identifier. Pattern: `^tech_\S+$`. Example: `tech_abcd1234`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `technique.name`         | string               | Yes      | Technique name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `action`                 | object or null       | No       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `action.action_id`       | string               | Yes      | Action identifier. One of: `color-grade-image-browser`, `overlay-image-browser`, `draw-image-browser`, `pixel-remover-image-browser`, `magic-eraser-image-browser`, `crop-image-browser`, `scene-3d-image-browser`, `blur-image-browser`, `change-image-ar-browser`, `rotate-image-browser`, `color-filter-image-browser`, `color-tint-image-browser`, `filter-color-image-browser`, `duplicate-image-browser`, `side-by-side-composite-browser`, `add-shape-to-image-browser`, `add-text-to-image-browser`, `qr-code-generator-browser`, `resize-image-browser`, `shader-effect-browser`, `split-text-browser`, `find-and-replace-text-browser`, `concat-text-browser`, `ken-burns-video`, `stitch-videos`, `split-video`, `extract-video-frames`, `color-grade-video`, `video-to-frame-grid`, `boomerang-video`, `reverse-video`, `video-to-long-exposure`, `video-effect`, `color-filter-video`, `speed-up-video`, `slow-down-video`, `duplicate-video`, `greenscreen-video`, `resize-video`, `change-video-ar`, and 2 more. |
| `estimated_seconds`      | integer or null      | Yes      | At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `charged_cost`           | number               | Yes      | Cost in USD. For a generation run, the list price of this request's parameters before any plan discount, and an estimate for usage-priced models; when the request cannot be priced in time, the model's price at default settings. GET /runs/{run\_id} reports the settled amount once the run completes. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `poll_url`               | string (uri) or null | No       | URL to poll pending/running runs or fetch completed/failed run details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `project_id`             | string or null       | No       | Project identifier. Pattern: `^prj_\S+$`. Example: `prj_abc123`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `canvas_url`             | string (uri) or null | No       | Link to the project canvas. Hand this to the user as-is; a URL built from project\_id does not resolve.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `warnings`               | array of objects     | No       | Warnings for accepted input (unknown parameters and applied preprocessing changes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `warnings[].code`        | string               | Yes      | Stable warning code                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `warnings[].message`     | string               | Yes      | Human-readable warning message                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `warnings[].field`       | string               | No       | Feature or parameter the warning relates to                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `node_id`                | string or null       | Yes      | Canvas node UUID the generation was seeded on, or null when add\_to\_canvas was false. Pass it as reference\_node\_ids on a follow-up generation to chain. At least 1 character. Example: `7f6ae6da-4a0e-4a2f-9c6a-2c1c6b8d1f21`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

**Shape 2: `type` is `generation_quote`.**

| Field                     | Type               | Required | Description                                                                |
| ------------------------- | ------------------ | -------- | -------------------------------------------------------------------------- |
| `type`                    | string             | Yes      | Always `generation_quote`.                                                 |
| `model`                   | object             | Yes      |                                                                            |
| `model.model_id`          | string             | Yes      |                                                                            |
| `estimated_usage_credits` | number             | Yes      | Pricing-v3 usage credits for one run; no credits are reserved. At least 0. |
| `estimated_cost`          | number             | Yes      | Estimated user cost in USD for the prepared request. At least 0.           |
| `currency`                | string             | Yes      | Always `USD`.                                                              |
| `is_estimate`             | boolean            | Yes      | Always true: estimates do not lock the final price.                        |
| `quoted_at`               | string (date-time) | Yes      |                                                                            |
| `expires_at`              | string (date-time) | Yes      | Requote after this time. This is not a price lock.                         |
| `assumptions`             | array of string    | Yes      |                                                                            |

### 201: Generation started, or a read-only quote returned.

Same body as 200.

## Errors

Every error has the same body: `error.code`, `error.message`, and `error.fields` on validation errors. See [Errors](https://docs.flora.ai/api/platform/errors.md) for how to recover from each code.

| Status | Code                                         | Meaning                                                                             |
| ------ | -------------------------------------------- | ----------------------------------------------------------------------------------- |
| 400    | `invalid_json`, `input_validation_error`     | The body isn't valid JSON, or an input failed validation (`fields` lists each one). |
| 401    | `unauthorized`, `invalid_api_key`            | The API key is missing, invalid or revoked.                                         |
| 402    | `insufficient_credits`                       | The workspace balance is too low for this request.                                  |
| 403    | `forbidden`, `paid_plan_required`            | The key can't do this, or the workspace plan doesn't include it.                    |
| 404    | `not_found`                                  | The resource doesn't exist or isn't visible to this key.                            |
| 409    | `idempotency_duplicate`, `revision_conflict` | Duplicate `Idempotency-Key` or a stale `base_revision`.                             |
| 429    | `rate_limited`                               | Too many requests. Back off and retry.                                              |
| 500    | `unknown_error`, `internal_error`            | Something failed on FLORA's side. Retry with backoff.                               |
| 503    | `temporarily_unavailable`                    | Authorization is temporarily unavailable. Retry later.                              |


---

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