Skip to content
FLORA FLORA API

Start a technique run

POST
/techniques/{techniqueId}/runs
 
import { FloraClient } from '@flora-ai/flora';


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


const run = await client.techniques.runs.create({
  techniqueId: '<techniqueId>',
  inputs: [
    {
      id: '<id>',
      type: 'text',
      value: '<value>',
    },
  ],
  mode: 'async',
});
console.log(run);

Starts a run for a specific technique using the backward-compatible nested route. 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 ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
techniqueId
required

Technique identifier or slug

string
/^\S+$/

Technique identifier or slug

Request Body required

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

Technique inputs. Media inputs (imageUrl, videoUrl) must be a Flora-hosted or allowlisted media URL. Upload external media via POST /assets first and pass the returned url.

Array<object>
object
id
required

Technique input identifier

string
type
required

Technique input type

string
Allowed values: text imageUrl videoUrl model3dUrl
value
required

Technique input value. For media inputs (imageUrl, videoUrl), this must be a Flora-hosted or allowlisted media URL. Upload external media via POST /assets first and pass the returned url.

string
mode
required

Technique run execution mode

string
Allowed values: async stream
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
idempotency_key

Idempotency key for safely retrying requests

string

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Technique run started.

Media type application/json
object
run_id
required

Run identifier

string
/^run_\S+$/
status
required
string
Allowed values: pending running completed failed
progress
required
number
created_at
required
number
started_at
number
completed_at
number
error_code

Machine-readable run error code

string
error_message

Human-readable run error message

string
charged_cost

Cost charged in USD

number
outputs
Array<object>
object
output_id
required

Run output identifier

string
type
required

Run output media type

string
Allowed values: imageUrl videoUrl audioUrl text documentUrl model3dUrl
url
required

Run output URL or text content

string
>= 1 characters
asset_id

Asset identifier for durable media outputs

string
/^asset_\S+$/
label

Optional output label

string
tri_count

Triangle count for model3d outputs

integer
bbox

Axis-aligned local bounds for model3d outputs

object
min
required
array
max
required
array
textured

Whether the model3d output carries textures

boolean
poll_url

URL to poll pending/running runs or fetch completed/failed run details.

string format: uri
Example 
{
  "run_id": "run_abc123",
  "status": "pending",
  "error_code": "provider_error",
  "error_message": "The provider failed to complete the generation.",
  "outputs": [
    {
      "output_id": "output_1",
      "type": "imageUrl",
      "url": "https://media.flora.ai/output.png",
      "asset_id": "asset_abc123",
      "label": "preview"
    }
  ]
}

201

Section titled “201 ”

Technique run started.

Media type application/json
object
run_id
required

Run identifier

string
/^run_\S+$/
status
required
string
Allowed values: pending running completed failed
progress
required
number
created_at
required
number
started_at
number
completed_at
number
error_code

Machine-readable run error code

string
error_message

Human-readable run error message

string
charged_cost

Cost charged in USD

number
outputs
Array<object>
object
output_id
required

Run output identifier

string
type
required

Run output media type

string
Allowed values: imageUrl videoUrl audioUrl text documentUrl model3dUrl
url
required

Run output URL or text content

string
>= 1 characters
asset_id

Asset identifier for durable media outputs

string
/^asset_\S+$/
label

Optional output label

string
tri_count

Triangle count for model3d outputs

integer
bbox

Axis-aligned local bounds for model3d outputs

object
min
required
array
max
required
array
textured

Whether the model3d output carries textures

boolean
poll_url

URL to poll pending/running runs or fetch completed/failed run details.

string format: uri
Example 
{
  "run_id": "run_abc123",
  "status": "pending",
  "error_code": "provider_error",
  "error_message": "The provider failed to complete the generation.",
  "outputs": [
    {
      "output_id": "output_1",
      "type": "imageUrl",
      "url": "https://media.flora.ai/output.png",
      "asset_id": "asset_abc123",
      "label": "preview"
    }
  ]
}