Start an action run
import { FloraClient } from '@flora-ai/flora';
const client = new FloraClient({ apiKey: process.env['FLORA_API_KEY'] });
const action = await client.actions.run({ action_id: '<action_id>', workspace_id: 'ws_abc123', project_id: 'prj_abc123', inputs: [ { type: 'image', }, ],});console.log(action);curl -X POST 'https://app.flora.ai/api/v1/runs/action' \ -H 'Authorization: Bearer $FLORA_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "action_id": "<action_id>", "workspace_id": "ws_abc123", "project_id": "prj_abc123", "inputs": [ { "type": "image" } ]}'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.
Error responses use the standard error body.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Warmth
Contrast
Saturation
Brightness
Highlights
Shadows
Tint (Green-Magenta)
Hue Shift (deg)
Show additional controls
Show Color Scope in preview
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Center
object
Size
object
Rotation (deg)
Opacity
Blend
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Brush color
Brush size
Erase
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Brush size
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Brush size
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Center
object
Size
object
Lock ratio
Rotation (deg)
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Shape
Color
Rotation (deg)
object
Offset
object
Scale
object
Include Background
Background Color
Aspect Ratio
Resolution (longest side)
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Mode
Blur Type
Radius
Motion Angle (°)
Radial Mode
Radial Strength
Edge Preservation
Bokeh Shape
Sharp Band Center
Sharp Band Width
Band Orientation
Target Color
Color Tolerance
Invert Selection (blur non-matching)
Brush Size (px)
Brush Hardness
Brush Intensity
Erase
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Aspect Ratio
Fit
Background
Pad Color
Blur Amount
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Angle (°, clockwise)
Flip
Canvas
Transparent Background
Background Color
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Filter
Intensity
Warmth
Threshold
Bits per channel
Threshold
Shadow Color
Highlight Color
Grain
Vignette Strength
Vignette Softness
Keep Color
Color Tolerance
Dot Size
Grid Angle (°)
Dot Color
Background
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Tint Color
Intensity
Blend Mode
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Target Color
Tolerance
Mode
Replacement Color
Edge Softness
Invert Selection
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Copies
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Layout
Size Match
Gap (px)
Background
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Shape
Width (px)
Height (px)
Include Background
Background Color
Center
object
Size
object
Rotation (deg)
Fill Color
Fill Opacity
Stroke Color
Stroke Width (px)
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Text
Dimensions (px)
object
Include Background
Background Color
Font
Font Size (px)
Text Color
Max Width (px)
Center
object
Rotation (deg)
Opacity
Shadow
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Size (px)
Foreground Color
Background Color
Error Correction
Quiet-Zone Border (modules)
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Resize by
Width (px)
Height (px)
Fit
Letterbox Color
Scale (%)
Longest Side (px)
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Effect
Intensity
Shift (px)
Glitch
Thickness
Scanlines
Frequency
Amplitude
Segments
Threshold
Strength
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Split Mode
Separator
Lines per Part
Characters per Part
Trim Whitespace
Skip Empty Parts
Max Parts
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Find
Replace With
Case Sensitive
Whole Word Only
Replace All Occurrences
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Separator
Prefix
Suffix
Wrap Each Part
Trim Each Part
Skip Empty Parts
Add Input Name Headers
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Duration (s)
Zoom Level
Zoom Direction
Pan
Easing
FPS
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Transition
Transition Duration (s)
Output Aspect Ratio
Fit Mode
Background Mode
Blur Amount
Background Color
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Split Mode
Number of Segments
Segment Duration (s)
Scene Sensitivity
Trim Handles (s)
Strip Audio
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Frames
Time (%)
Frame Count
Every (s)
Scene Sensitivity
Video Range (%)
object
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Contrast
Saturation
Brightness
Gamma
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Rows
Columns
Cell Width (px)
Gap Between Cells (px)
Background Color
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Speed
Include Audio
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Audio
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Blend Mode
Frame Stride (sample every N frames)
Max Frames to Sample
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Effect
Vignette Falloff
Grain Strength
Block Size (px)
Shake Amount (px)
Channel Offset (px)
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Filter
B&W Threshold
Posterize Bits
Solarize Threshold
Grain
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Speed Factor (x)
Keep Audio (pitch-preserved)
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Slow Factor (x)
Keep Audio (pitch-preserved)
Smoothing
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Copies
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Background Preset
Custom Background Color
Similarity (how close to key color counts)
Edge Blend (softness)
Spill Suppression
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Resolution
Custom Resolution (px)
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Aspect Ratio
Fit
Background
Pad Color
Blur Amount
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Audio Format
object
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_. Used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.
Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.
object
Action input type
Input media URL
Asset identifier for model3d inputs
Input text value
Optional input name
Action parameters
object
Duration
Responses
Section titled “ Responses ”Action run started.
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
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"}