FLflorafauna-ai
Generations

Start a generation

Changed on

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.

post/generate

Request

  • Base URL
    https://app.flora.ai/api/v1
  • URL
    https://app.flora.ai/api/v1/generate
  • Auth
    HTTP bearer

Request body

quoteboolean

Return a quote without starting a generation or reserving credits. Requires the generation_quote API capability.

type'image' | 'video' | 'audio' | 'text' | 'model3d' required

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

promptstring required

Generation prompt

modelstring

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

workspace_idstring required

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

project_idstring required

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

paramsobject

Model parameters

reference_node_idsstring[]

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

add_to_canvasboolean

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

callback_urlstring uri

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.

Example request

{
  "prompt": "A cinematic product photo of a ceramic mug on a sunlit table",
  "model": "t2i-flux-2-pro",
  "workspace_id": "ws_abc123",
  "project_id": "prj_abc123",
  "reference_node_ids": [
    "7f6ae6da-4a0e-4a2f-9c6a-2c1c6b8d1f21"
  ]
}

Response

Generation started, or a read-only quote returned.

OR

Example response

{
  "run_id": "run_abc123",
  "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"
}

Changes

  • a8351619f225Revision changes
    • warning

      added the new not_configured enum value to the / response property for the response status

    • warning

      added the new not_configured enum value to the / response property for the response status

    • warning

      added the new not_configured enum value to the / response property for the response status

    • warning

      added the new not_configured enum value to the / response property for the response status

    • warning

      added the new not_configured enum value to the / response property for the response status

    • warning

      added the new not_configured enum value to the / response property for the response status

    • warning

      added the new not_configured enum value to the / response property for the response status

    • warning

      added the new not_configured enum value to the / response property for the response status

    • warning

      added the new not_configured enum value to the / response property for the response status

  • 6c2e9b6f0c7bRevision changes
    • breaking

      response property anyOf[subschema #1]/node_id list-of-types was widened by adding types null to media type application/json of response 200

    • breaking

      response property anyOf[subschema #1]/node_id list-of-types was widened by adding types null to media type application/json of response 201

    • breaking

      the / response property's minLength was decreased from 1 to 0 for the response status

    • breaking

      the / response property's minLength was decreased from 1 to 0 for the response status

    • info

      added the new optional request property