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 input images (image-to-image chaining). Each node must be in project_id and have a completed image output; 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 image inputs, 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); 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 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
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"
}