Start an action run

client.actions.run(, ?): ActionRunResponse { charged_cost, estimated_seconds, run_id, 6 more }

POST/runs/action

Starts a headless prebuilt action run using raw action slugs such as rotate-image, workspace_id, project_id, and non-empty inputs. Direct action runs do not create or mutate canvas nodes. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.

ParametersExpand Collapse

ActionRunParams = Variant0 | Variant1 | Variant2 | 37 more

ActionRunParamsBase { action_id, inputs, project_id, 2 more }

action_id: "color-grade-image-browser"

inputs: Array<Input>

Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.

type: "image" | "video" | "audio" | "text"

Action input type

One of the following:

"image"

"video"

"audio"

"text"

name?: string

Optional input name

text?: string

Input text value

url?: string

Input media URL

formaturi

project_id: string

Project identifier. Use the public API ID returned by list projects; it must start with prj_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.

workspace_id: string

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

params?: Params

Action parameters

advanced?: boolean

Show additional controls

brightness?: number

Brightness

minimum0.5

maximum1.5

contrast?: number

Contrast

minimum0.5

maximum2

highlights?: number

Highlights

minimum-1

maximum1

hue_shift?: number

Hue Shift (deg)

minimum-180

maximum180

saturation?: number

Saturation

minimum0

maximum2

shadows?: number

Shadows

minimum-1

maximum1

show_scope?: boolean

Show Color Scope in preview

tint?: number

Tint (Green-Magenta)

minimum-1

maximum1

warmth?: number

Warmth

minimum-0.5

maximum0.5

Variant0 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant1 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant2 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant3 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant4 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant5 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant6 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant7 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant8 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant9 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant10 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant11 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant12 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant13 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant14 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant15 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant16 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant17 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant18 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant19 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant20 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant21 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant22 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant23 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant24 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant25 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant26 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant27 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant28 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant29 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant30 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant31 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant32 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant33 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant34 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant35 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant36 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant37 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant38 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

Variant39 extends ActionRunParamsBase { action_id, inputs, project_id, 2 more }

ReturnsExpand Collapse

ActionRunResponse { charged_cost, estimated_seconds, run_id, 6 more }

charged_cost: number

Cost charged in USD

minimum0

estimated_seconds: number | null

minimum0

run_id: string

Run identifier

type: "generation" | "technique" | "action"

Run type

One of the following:

"generation"

"technique"

"action"

action?: Action | null

action_id: "color-grade-image-browser" | "overlay-image-browser" | "draw-image-browser" | 37 more

Action identifier

One of the following:

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

model?: Model | null

model_id: string

Model identifier

minLength1

poll_url?: string | null

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

formaturi

project_id?: string | null

Project identifier

technique?: Technique | null

name: string

Technique name

technique_id: string

Technique identifier

Start an action run

import FLORA from '@flora-ai/flora';

const client = new FLORA({
  apiKey: process.env['FLORA_API_KEY'], // This is the default and can be omitted
});

const response = await client.actions.run({
  action_id: 'color-grade-image-browser',
  inputs: [{ type: 'image' }],
  project_id: 'prj_abc123',
  workspace_id: 'ws_abc123',
});

console.log(response.run_id);

{
  "charged_cost": 0,
  "estimated_seconds": 0,
  "run_id": "run_abc123",
  "type": "generation",
  "action": {
    "action_id": "color-grade-image-browser"
  },
  "model": {
    "model_id": "t2i-flux-2-pro"
  },
  "poll_url": "https://example.com",
  "project_id": "prj_abc123",
  "technique": {
    "name": "name",
    "technique_id": "tech_abcd1234"
  }
}

{
  "error": {
    "code": "input_validation_error",
    "message": "prompt: Required",
    "fields": [
      {
        "field": "prompt",
        "message": "Required"
      }
    ]
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key."
  }
}

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits."
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Forbidden."
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Not found."
  }
}

{
  "error": {
    "code": "idempotency_duplicate",
    "message": "Duplicate idempotency key."
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}

{
  "error": {
    "code": "unknown_error",
    "message": "An unknown error occurred."
  }
}

Returns Examples

{
  "charged_cost": 0,
  "estimated_seconds": 0,
  "run_id": "run_abc123",
  "type": "generation",
  "action": {
    "action_id": "color-grade-image-browser"
  },
  "model": {
    "model_id": "t2i-flux-2-pro"
  },
  "poll_url": "https://example.com",
  "project_id": "prj_abc123",
  "technique": {
    "name": "name",
    "technique_id": "tech_abcd1234"
  }
}

{
  "error": {
    "code": "input_validation_error",
    "message": "prompt: Required",
    "fields": [
      {
        "field": "prompt",
        "message": "Required"
      }
    ]
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key."
  }
}

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits."
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Forbidden."
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Not found."
  }
}

{
  "error": {
    "code": "idempotency_duplicate",
    "message": "Duplicate idempotency key."
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}

{
  "error": {
    "code": "unknown_error",
    "message": "An unknown error occurred."
  }
}