Skip to content
FLORA FLORA API

Start a generation

POST
/generate
 
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);

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. 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.

Error responses use the standard error body.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
type
required

Generation type. Use “image”, “video”, “audio”, “text”, or “model3d”; do not pass model families such as “t2i” or “i2v”.

string
Allowed values: image video audio text model3d
prompt
required

Generation prompt

string
>= 1 characters
model

Model endpoint ID, not a display name. Use list_models (or GET /models) to find accessible endpoint IDs for the requested type.

string
workspace_id
required

Workspace identifier. Use the public API ID returned by list workspaces; it must start with ws_.

string
project_id
required

Project identifier. Use the public API ID returned by list projects; it must start with prj_.

string
params

Model parameters

object
key
additional properties
any
reference_node_ids

Canvas node UUIDs 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 or model3d sources. 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, or model_url — see GET /models), and draws an edge from each source node to the new node. Video and audio sources are rejected with invalid_parameters. Requires an image-to-image capable model (type=image) or a model3d model that accepts image or model3d inputs; other models are rejected with invalid_parameters. @[nodeId] markers in prompt are unioned into this list automatically.

Array<string>
<= 20 items
callback_url

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 docs/system-overviews/webhooks.md for the payload schema and verification example.

string format: uri

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Generation started.

Media type application/json
object
run_id
required

Run identifier

string
/^run_\S+$/
type
required

Run type

string
Allowed values: generation technique action
model
Any of:
object
model_id
required

Model identifier

string
>= 1 characters
technique
Any of:
object
technique_id
required

Technique identifier

string
/^tech_\S+$/
name
required

Technique name

string
action
Any of:
object
action_id
required

Action identifier

string
Allowed values: 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 split-audio-from-video merge-audio-into-video
estimated_seconds
required
Any of:
integer
charged_cost
required

Cost charged in USD

number
poll_url
Any of:
string format: uri
project_id
Any of:

Project identifier

string
/^prj_\S+$/
canvas_url
Any of:
string format: uri
warnings

Warnings for accepted input (unknown parameters and applied preprocessing changes)

Array<object>
object
code
required

Stable warning code

string
message
required

Human-readable warning message

string
field

Feature or parameter the warning relates to

string
node_id
required

Canvas node UUID the generation was seeded on. Pass it as reference_node_ids on a follow-up generation to chain.

string
>= 1 characters
Example 
{
  "run_id": "run_abc123",
  "type": "generation",
  "model": {
    "model_id": "t2i-flux-2-pro"
  },
  "technique": {
    "technique_id": "tech_abcd1234"
  },
  "action": {
    "action_id": "color-grade-image-browser"
  },
  "project_id": "prj_abc123",
  "node_id": "7f6ae6da-4a0e-4a2f-9c6a-2c1c6b8d1f21"
}