Start a generation
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);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"}'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. 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 ”object
Return a quote without starting a generation or reserving credits. Requires the generation_quote API capability.
Generation type. Use “image”, “video”, “audio”, “text”, or “model3d”; do not pass model families such as “t2i” or “i2v”.
Generation prompt
Model endpoint ID, not a display name. Use list_models (or GET /models) to find accessible endpoint IDs for the requested type.
Workspace identifier. Use the public API ID returned by list workspaces; it must start with ws_.
Project identifier. Use the public API ID returned by list projects; it must start with prj_.
Model parameters
object
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 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. 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 invalid_parameters rejection. The response reports the model actually used. @[nodeId] markers in prompt are unioned into this list automatically.
Pinned brand context from GET /brands/{brandId}/context; the server reloads the profile’s rules at that release, appends them to the prompt and attaches the profile’s image assets plus any imagery bank images named in asset_keys as style references. Supported for image generation only.
object
Brand identifier returned by list brands
Release the rules were read from, such as v3 or brel_abc123; omitted means live
Older pin from a brand snapshot; a release id is honored, anything else reads live
Task profile key, such as image.generate
Optional channel filter
Explicit subset of the task profile’s modules. Whole rules are preserved; required dependency modules must also be selected. Omit for the complete profile.
Image assets to attach: masters the profile includes, and up to three asset_keys from imagery.bank as style references. Omit for every master image the profile includes; bank images never attach unless named. A list replaces that default, so name any masters you still want; an empty array attaches none. Bank images are refused under the bank-only imagery policy
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.
Responses
Section titled “ Responses ”Generation started, or a read-only quote returned.
object
Run identifier
Run type
Cost charged in USD
Warnings for accepted input (unknown parameters and applied preprocessing changes)
object
Stable warning code
Human-readable warning message
Feature or parameter the warning relates to
Canvas node UUID the generation was seeded on. Pass it as reference_node_ids on a follow-up generation to chain.
Brand OS brand, release, rules and images this generation runs with
object
Brand identifier
Release version the run read, such as “v3”
Task profile key the run used, such as image.generate
Where the brand applied: an API or agent generation, a canvas project’s brand step, or render_text
Rules that shaped the run, as ruleKey@vN
Brand masters attached as inputs: images, logos and fonts
Imagery bank photos used, as style references or painted as they are
Where the imagery came from: the bank, a model, or both. Absent when the output carries no photo or generated image
Layout path the output filled
Canvas: whether the brand step rewrote the prompt
object
object
Pricing-v3 usage credits for one run; no credits are reserved.
Estimated user cost in USD for the prepared request.
Always true: estimates do not lock the final price.
Requote after this time. This is not a price lock.
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", "brand": { "brand_id": "brand_abc123", "surface": "api", "imagery": "bank" }}Generation started, or a read-only quote returned.
object
Run identifier
Run type
Cost charged in USD
Warnings for accepted input (unknown parameters and applied preprocessing changes)
object
Stable warning code
Human-readable warning message
Feature or parameter the warning relates to
Canvas node UUID the generation was seeded on. Pass it as reference_node_ids on a follow-up generation to chain.
Brand OS brand, release, rules and images this generation runs with
object
Brand identifier
Release version the run read, such as “v3”
Task profile key the run used, such as image.generate
Where the brand applied: an API or agent generation, a canvas project’s brand step, or render_text
Rules that shaped the run, as ruleKey@vN
Brand masters attached as inputs: images, logos and fonts
Imagery bank photos used, as style references or painted as they are
Where the imagery came from: the bank, a model, or both. Absent when the output carries no photo or generated image
Layout path the output filled
Canvas: whether the brand step rewrote the prompt
object
object
Pricing-v3 usage credits for one run; no credits are reserved.
Estimated user cost in USD for the prepared request.
Always true: estimates do not lock the final price.
Requote after this time. This is not a price lock.
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", "brand": { "brand_id": "brand_abc123", "surface": "api", "imagery": "bank" }}