> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/api/reference/runs/createactionrun.md).

# Start an action run

Start an action run with the FLORA API: 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.

```http
POST https://app.flora.ai/api/v1/runs/action
```

* **Auth:** API key as a bearer token, `Authorization: Bearer $FLORA_API_KEY`. See [Authentication](https://docs.flora.ai/api/platform/authentication.md).
* **TypeScript SDK:** `client.actions.run()`.
* **Idempotency:** optional `Idempotency-Key` header. See [Idempotency](https://docs.flora.ai/api/platform/idempotency.md).
* **Operation ID:** `createActionRun`.

## Example

{% tabs %}
{% tab title="cURL" %}

```bash
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": "color-grade-image-browser",
  "workspace_id": "ws_abc123",
  "project_id": "prj_abc123",
  "inputs": [
    {
      "type": "image"
    }
  ]
}'
```

{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
import { FloraClient } from '@flora-ai/flora';

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

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

{% endtab %}
{% endtabs %}

## Request body

Required.

The body takes one of 42 shapes, set by `action_id`.

Fields every shape has:

| Field               | Type             | Required | Description                                                                                                                                                                                                                                    |
| ------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspace_id`      | string           | Yes      | Workspace identifier. Use the public API ID returned by list workspaces; it must start with ws\_. Pattern: `^ws_\S+$`. Example: `ws_abc123`.                                                                                                   |
| `project_id`        | string           | Yes      | 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. Pattern: `^prj_\S+$`. Example: `prj_abc123`. |
| `inputs`            | array of objects | Yes      | Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges. At least 1 item.                                                                                                                       |
| `inputs[].type`     | string           | Yes      | Action input type. One of: `image`, `video`, `audio`, `text`, `model3d`.                                                                                                                                                                       |
| `inputs[].url`      | string (uri)     | No       | Input media URL                                                                                                                                                                                                                                |
| `inputs[].asset_id` | string           | No       | Asset identifier for model3d inputs. Pattern: `^asset_\S+$`. Example: `asset_abc123`.                                                                                                                                                          |
| `inputs[].text`     | string           | No       | Input text value                                                                                                                                                                                                                               |
| `inputs[].name`     | string           | No       | Optional input name                                                                                                                                                                                                                            |
| `params`            | object           | No       | Action parameters                                                                                                                                                                                                                              |
| `state`             | any              | No       | Interaction state committed by the action's live preview (JSON, at most 256 KiB), replayed by the run exactly as the canvas replays a node's own state. Only meaningful for browser-runtime actions; omit otherwise.                           |

Fields that depend on the shape:

<details>

<summary>Shape 1: action_id is color-grade-image-browser</summary>

| Field               | Type    | Required | Description                         |
| ------------------- | ------- | -------- | ----------------------------------- |
| `action_id`         | string  | Yes      | Always `color-grade-image-browser`. |
| `params.warmth`     | number  | No       | Warmth. -0.5 to 0.5.                |
| `params.contrast`   | number  | No       | Contrast. 0.5 to 2.                 |
| `params.saturation` | number  | No       | Saturation. 0 to 2.                 |
| `params.brightness` | number  | No       | Brightness. 0.5 to 1.5.             |
| `params.highlights` | number  | No       | Highlights. -1 to 1.                |
| `params.shadows`    | number  | No       | Shadows. -1 to 1.                   |
| `params.tint`       | number  | No       | Tint (Green-Magenta). -1 to 1.      |
| `params.hue_shift`  | number  | No       | Hue Shift (deg). -180 to 180.       |
| `params.advanced`   | boolean | No       | Show additional controls            |
| `params.show_scope` | boolean | No       | Show Color Scope in preview         |

</details>

<details>

<summary>Shape 2: action_id is overlay-image-browser</summary>

| Field             | Type   | Required | Description                                                             |
| ----------------- | ------ | -------- | ----------------------------------------------------------------------- |
| `action_id`       | string | Yes      | Always `overlay-image-browser`.                                         |
| `params.center`   | object | No       | Center                                                                  |
| `params.center.x` | number | Yes      | 0 to 1.                                                                 |
| `params.center.y` | number | Yes      | 0 to 1.                                                                 |
| `params.size`     | object | No       | Size                                                                    |
| `params.size.x`   | number | Yes      | 0.01 to 1.                                                              |
| `params.size.y`   | number | Yes      | 0.01 to 1.                                                              |
| `params.rotation` | number | No       | Rotation (deg). -180 to 180.                                            |
| `params.opacity`  | number | No       | Opacity. 0 to 1.                                                        |
| `params.blend`    | string | No       | Blend. One of: `normal`, `multiply`, `screen`, `overlay`, `soft-light`. |

</details>

<details>

<summary>Shape 3: action_id is draw-image-browser</summary>

| Field          | Type    | Required | Description                  |
| -------------- | ------- | -------- | ---------------------------- |
| `action_id`    | string  | Yes      | Always `draw-image-browser`. |
| `params.color` | string  | No       | Brush color                  |
| `params.size`  | number  | No       | Brush size. 1 to 64.         |
| `params.erase` | boolean | No       | Erase                        |

</details>

<details>

<summary>Shape 4: action_id is pixel-remover-image-browser</summary>

| Field         | Type   | Required | Description                           |
| ------------- | ------ | -------- | ------------------------------------- |
| `action_id`   | string | Yes      | Always `pixel-remover-image-browser`. |
| `params.size` | number | No       | Brush size. 1 to 128.                 |

</details>

<details>

<summary>Shape 5: action_id is magic-eraser-image-browser</summary>

| Field         | Type   | Required | Description                          |
| ------------- | ------ | -------- | ------------------------------------ |
| `action_id`   | string | Yes      | Always `magic-eraser-image-browser`. |
| `params.size` | number | No       | Brush size. 1 to 128.                |

</details>

<details>

<summary>Shape 6: action_id is crop-image-browser</summary>

| Field                | Type    | Required | Description                  |
| -------------------- | ------- | -------- | ---------------------------- |
| `action_id`          | string  | Yes      | Always `crop-image-browser`. |
| `params.center`      | object  | No       | Center                       |
| `params.center.x`    | number  | Yes      | 0 to 1.                      |
| `params.center.y`    | number  | Yes      | 0 to 1.                      |
| `params.size`        | object  | No       | Size                         |
| `params.size.x`      | number  | Yes      | 0.02 to 1.                   |
| `params.size.y`      | number  | Yes      | 0.02 to 1.                   |
| `params.lock_aspect` | boolean | No       | Lock ratio                   |
| `params.rotation`    | number  | No       | Rotation (deg). -180 to 180. |

</details>

<details>

<summary>Shape 7: action_id is scene-3d-image-browser</summary>

| Field                    | Type    | Required | Description                                                   |
| ------------------------ | ------- | -------- | ------------------------------------------------------------- |
| `action_id`              | string  | Yes      | Always `scene-3d-image-browser`.                              |
| `params.shape`           | string  | No       | Shape. One of: `cube`, `sphere`, `torus`, `cone`, `cylinder`. |
| `params.color`           | string  | No       | Color                                                         |
| `params.rotation`        | object  | No       | Rotation (deg)                                                |
| `params.rotation.x`      | number  | Yes      | -180 to 180.                                                  |
| `params.rotation.y`      | number  | Yes      | -180 to 180.                                                  |
| `params.rotation.z`      | number  | Yes      | -180 to 180.                                                  |
| `params.offset`          | object  | No       | Offset                                                        |
| `params.offset.x`        | number  | Yes      | -1 to 1.                                                      |
| `params.offset.y`        | number  | Yes      | -1 to 1.                                                      |
| `params.scale`           | object  | No       | Scale                                                         |
| `params.scale.x`         | number  | Yes      | 0.1 to 3.                                                     |
| `params.scale.y`         | number  | Yes      | 0.1 to 3.                                                     |
| `params.scale.z`         | number  | Yes      | 0.1 to 3.                                                     |
| `params.show_background` | boolean | No       | Include Background                                            |
| `params.background`      | string  | No       | Background Color                                              |
| `params.aspect_ratio`    | string  | No       | Aspect Ratio. One of: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`.    |
| `params.size`            | number  | No       | Resolution (longest side). 256 to 2048.                       |

</details>

<details>

<summary>Shape 8: action_id is blur-image-browser</summary>

| Field                     | Type    | Required | Description                                                                                                 |
| ------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `action_id`               | string  | Yes      | Always `blur-image-browser`.                                                                                |
| `params.mode`             | string  | No       | Mode. One of: `full`, `draw`.                                                                               |
| `params.blur_type`        | string  | No       | Blur Type. One of: `gaussian`, `box`, `motion`, `radial`, `bilateral`, `bokeh`, `tiltshift`, `targetcolor`. |
| `params.radius`           | number  | No       | Radius. 0 to 100.                                                                                           |
| `params.angle`            | number  | No       | Motion Angle (°). 0 to 360.                                                                                 |
| `params.radial_mode`      | string  | No       | Radial Mode. One of: `zoom`, `spin`.                                                                        |
| `params.radial_strength`  | number  | No       | Radial Strength. 0.01 to 1.                                                                                 |
| `params.edge_threshold`   | number  | No       | Edge Preservation. 5 to 200.                                                                                |
| `params.bokeh_shape`      | string  | No       | Bokeh Shape. One of: `circle`, `hexagon`, `pentagon`.                                                       |
| `params.tilt_center`      | number  | No       | Sharp Band Center. 0 to 1.                                                                                  |
| `params.tilt_width`       | number  | No       | Sharp Band Width. 0.05 to 1.                                                                                |
| `params.tilt_orientation` | string  | No       | Band Orientation. One of: `horizontal`, `vertical`.                                                         |
| `params.target_color`     | string  | No       | Target Color                                                                                                |
| `params.target_tolerance` | number  | No       | Color Tolerance. 1 to 255.                                                                                  |
| `params.target_invert`    | boolean | No       | Invert Selection (blur non-matching)                                                                        |
| `params.brush_size`       | number  | No       | Brush Size (px). 4 to 800.                                                                                  |
| `params.brush_hardness`   | number  | No       | Brush Hardness. 0 to 1.                                                                                     |
| `params.brush_intensity`  | number  | No       | Brush Intensity. 0.05 to 1.                                                                                 |
| `params.erase`            | boolean | No       | Erase                                                                                                       |

</details>

<details>

<summary>Shape 9: action_id is change-image-ar-browser</summary>

| Field                    | Type   | Required | Description                                                                      |
| ------------------------ | ------ | -------- | -------------------------------------------------------------------------------- |
| `action_id`              | string | Yes      | Always `change-image-ar-browser`.                                                |
| `params.aspect_ratio`    | string | No       | Aspect Ratio. One of: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9`. |
| `params.fit`             | string | No       | Fit. One of: `crop`, `pad`.                                                      |
| `params.background_mode` | string | No       | Background. One of: `solid`, `blur`.                                             |
| `params.pad_color`       | string | No       | Pad Color                                                                        |
| `params.blur_amount`     | number | No       | Blur Amount. 4 to 60.                                                            |

</details>

<details>

<summary>Shape 10: action_id is rotate-image-browser</summary>

| Field                | Type    | Required | Description                                             |
| -------------------- | ------- | -------- | ------------------------------------------------------- |
| `action_id`          | string  | Yes      | Always `rotate-image-browser`.                          |
| `params.angle`       | number  | No       | Angle (°, clockwise). -360 to 360.                      |
| `params.direction`   | string  | No       | Flip. One of: `none`, `horizontal`, `vertical`, `both`. |
| `params.canvas_mode` | string  | No       | Canvas. One of: `shrink`, `keep`, `expand`.             |
| `params.transparent` | boolean | No       | Transparent Background                                  |
| `params.background`  | string  | No       | Background Color                                        |

</details>

<details>

<summary>Shape 11: action_id is color-filter-image-browser</summary>

| Field                       | Type   | Required | Description                                                                                                                                                                                     |
| --------------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action_id`                 | string | Yes      | Always `color-filter-image-browser`.                                                                                                                                                            |
| `params.filter`             | string | No       | Filter. One of: `grayscale`, `sepia`, `invert`, `bw`, `posterize`, `solarize`, `duotone`, `clarendon`, `moon`, `nashville`, `noir`, `fade`, `vignette`, `colorpop`, `crossprocess`, `halftone`. |
| `params.intensity`          | number | No       | Intensity. 0 to 1.                                                                                                                                                                              |
| `params.sepia_warmth`       | number | No       | Warmth. 0 to 2.                                                                                                                                                                                 |
| `params.bw_threshold`       | number | No       | Threshold. 0 to 255.                                                                                                                                                                            |
| `params.posterize_bits`     | number | No       | Bits per channel. 1 to 8.                                                                                                                                                                       |
| `params.solarize_threshold` | number | No       | Threshold. 0 to 255.                                                                                                                                                                            |
| `params.shadow_color`       | string | No       | Shadow Color                                                                                                                                                                                    |
| `params.highlight_color`    | string | No       | Highlight Color                                                                                                                                                                                 |
| `params.grain`              | number | No       | Grain. 0 to 50.                                                                                                                                                                                 |
| `params.vignette_strength`  | number | No       | Vignette Strength. 0 to 1.                                                                                                                                                                      |
| `params.vignette_softness`  | number | No       | Vignette Softness. 0.05 to 1.                                                                                                                                                                   |
| `params.target_color`       | string | No       | Keep Color                                                                                                                                                                                      |
| `params.colorpop_tolerance` | number | No       | Color Tolerance. 1 to 255.                                                                                                                                                                      |
| `params.dot_size`           | number | No       | Dot Size. 3 to 40.                                                                                                                                                                              |
| `params.dot_angle`          | number | No       | Grid Angle (°). 0 to 90.                                                                                                                                                                        |
| `params.dot_color`          | string | No       | Dot Color                                                                                                                                                                                       |
| `params.dot_bg`             | string | No       | Background                                                                                                                                                                                      |

</details>

<details>

<summary>Shape 12: action_id is color-tint-image-browser</summary>

| Field               | Type   | Required | Description                                                                 |
| ------------------- | ------ | -------- | --------------------------------------------------------------------------- |
| `action_id`         | string | Yes      | Always `color-tint-image-browser`.                                          |
| `params.color`      | string | No       | Tint Color                                                                  |
| `params.intensity`  | number | No       | Intensity. 0 to 1.                                                          |
| `params.blend_mode` | string | No       | Blend Mode. One of: `multiply`, `screen`, `overlay`, `soft_light`, `color`. |

</details>

<details>

<summary>Shape 13: action_id is filter-color-image-browser</summary>

| Field                      | Type    | Required | Description                                |
| -------------------------- | ------- | -------- | ------------------------------------------ |
| `action_id`                | string  | Yes      | Always `filter-color-image-browser`.       |
| `params.target_color`      | string  | No       | Target Color                               |
| `params.tolerance`         | number  | No       | Tolerance. 0 to 255.                       |
| `params.mode`              | string  | No       | Mode. One of: `remove`, `replace`, `keep`. |
| `params.replacement_color` | string  | No       | Replacement Color                          |
| `params.softness`          | number  | No       | Edge Softness. 0 to 64.                    |
| `params.invert`            | boolean | No       | Invert Selection                           |

</details>

<details>

<summary>Shape 14: action_id is duplicate-image-browser</summary>

| Field          | Type   | Required | Description                       |
| -------------- | ------ | -------- | --------------------------------- |
| `action_id`    | string | Yes      | Always `duplicate-image-browser`. |
| `params.count` | number | No       | Copies. 1 to 20.                  |

</details>

<details>

<summary>Shape 15: action_id is side-by-side-composite-browser</summary>

| Field               | Type   | Required | Description                                                                                     |
| ------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `action_id`         | string | Yes      | Always `side-by-side-composite-browser`.                                                        |
| `params.layout`     | string | No       | Layout. One of: `auto`, `horizontal-2`, `horizontal-3`, `vertical-2`, `vertical-3`, `grid-2x2`. |
| `params.normalize`  | string | No       | Size Match. One of: `match-shortest`, `match-largest`, `pad-to-largest`.                        |
| `params.gap`        | number | No       | Gap (px). 0 to 200.                                                                             |
| `params.background` | string | No       | Background                                                                                      |

</details>

<details>

<summary>Shape 16: action_id is add-shape-to-image-browser</summary>

| Field                    | Type    | Required | Description                                                           |
| ------------------------ | ------- | -------- | --------------------------------------------------------------------- |
| `action_id`              | string  | Yes      | Always `add-shape-to-image-browser`.                                  |
| `params.shape`           | string  | No       | Shape. One of: `rectangle`, `ellipse`, `triangle`, `star`, `hexagon`. |
| `params.width`           | number  | No       | Width (px). 64 to 4096.                                               |
| `params.height`          | number  | No       | Height (px). 64 to 4096.                                              |
| `params.show_background` | boolean | No       | Include Background                                                    |
| `params.background`      | string  | No       | Background Color                                                      |
| `params.center`          | object  | No       | Center                                                                |
| `params.center.x`        | number  | Yes      | 0 to 1.                                                               |
| `params.center.y`        | number  | Yes      | 0 to 1.                                                               |
| `params.size`            | object  | No       | Size                                                                  |
| `params.size.x`          | number  | Yes      | 0.01 to 1.                                                            |
| `params.size.y`          | number  | Yes      | 0.01 to 1.                                                            |
| `params.rotation`        | number  | No       | Rotation (deg). -180 to 180.                                          |
| `params.fill_color`      | string  | No       | Fill Color                                                            |
| `params.fill_opacity`    | number  | No       | Fill Opacity. 0 to 1.                                                 |
| `params.stroke_color`    | string  | No       | Stroke Color                                                          |
| `params.stroke_width`    | number  | No       | Stroke Width (px). 0 to 50.                                           |

</details>

<details>

<summary>Shape 17: action_id is add-text-to-image-browser</summary>

| Field                    | Type    | Required | Description                                                                                   |
| ------------------------ | ------- | -------- | --------------------------------------------------------------------------------------------- |
| `action_id`              | string  | Yes      | Always `add-text-to-image-browser`.                                                           |
| `params.text`            | string  | No       | Text                                                                                          |
| `params.dimensions`      | object  | No       | Dimensions (px)                                                                               |
| `params.dimensions.x`    | number  | Yes      | 64 to 4096.                                                                                   |
| `params.dimensions.y`    | number  | Yes      | 64 to 4096.                                                                                   |
| `params.show_background` | boolean | No       | Include Background                                                                            |
| `params.background`      | string  | No       | Background Color                                                                              |
| `params.font_family`     | string  | No       | Font. One of: `sans`, `sans-bold`, `sans-italic`, `serif`, `serif-bold`, `mono`, `mono-bold`. |
| `params.font_size`       | number  | No       | Font Size (px). 8 to 512.                                                                     |
| `params.color`           | string  | No       | Text Color                                                                                    |
| `params.max_width`       | number  | No       | Max Width (px). 1 to 4096.                                                                    |
| `params.center`          | object  | No       | Center                                                                                        |
| `params.center.x`        | number  | Yes      | 0 to 1.                                                                                       |
| `params.center.y`        | number  | Yes      | 0 to 1.                                                                                       |
| `params.rotation`        | number  | No       | Rotation (deg). -180 to 180.                                                                  |
| `params.opacity`         | number  | No       | Opacity. 0 to 1.                                                                              |
| `params.shadow`          | boolean | No       | Shadow                                                                                        |

</details>

<details>

<summary>Shape 18: action_id is qr-code-generator-browser</summary>

| Field                     | Type   | Required | Description                                   |
| ------------------------- | ------ | -------- | --------------------------------------------- |
| `action_id`               | string | Yes      | Always `qr-code-generator-browser`.           |
| `params.size`             | number | No       | Size (px). 64 to 4096.                        |
| `params.fg_color`         | string | No       | Foreground Color                              |
| `params.bg_color`         | string | No       | Background Color                              |
| `params.error_correction` | string | No       | Error Correction. One of: `L`, `M`, `Q`, `H`. |
| `params.border`           | number | No       | Quiet-Zone Border (modules). 0 to 20.         |

</details>

<details>

<summary>Shape 19: action_id is resize-image-browser</summary>

| Field             | Type   | Required | Description                                       |
| ----------------- | ------ | -------- | ------------------------------------------------- |
| `action_id`       | string | Yes      | Always `resize-image-browser`.                    |
| `params.mode`     | string | No       | Resize by. One of: `exact`, `percent`, `longest`. |
| `params.width`    | number | No       | Width (px). 1 to 8192.                            |
| `params.height`   | number | No       | Height (px). 1 to 8192.                           |
| `params.fit`      | string | No       | Fit. One of: `contain`, `cover`, `stretch`.       |
| `params.bg_color` | string | No       | Letterbox Color                                   |
| `params.percent`  | number | No       | Scale (%). 1 to 400.                              |
| `params.longest`  | number | No       | Longest Side (px). 1 to 8192.                     |

</details>

<details>

<summary>Shape 20: action_id is shader-effect-browser</summary>

| Field                      | Type   | Required | Description                                                                                           |
| -------------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `action_id`                | string | Yes      | Always `shader-effect-browser`.                                                                       |
| `params.effect`            | string | No       | Effect. One of: `chromatic`, `glitch`, `edges`, `crt`, `ripple`, `kaleidoscope`, `bloom`, `pixelate`. |
| `params.intensity`         | number | No       | Intensity. 0 to 1.                                                                                    |
| `params.shift`             | number | No       | Shift (px). 0 to 40.                                                                                  |
| `params.glitch_amount`     | number | No       | Glitch. 0 to 1.                                                                                       |
| `params.edge_thickness`    | number | No       | Thickness. 0.5 to 3.                                                                                  |
| `params.scanline_strength` | number | No       | Scanlines. 0 to 1.                                                                                    |
| `params.ripple_freq`       | number | No       | Frequency. 1 to 60.                                                                                   |
| `params.ripple_amp`        | number | No       | Amplitude. 0 to 0.1.                                                                                  |
| `params.segments`          | number | No       | Segments. 2 to 24.                                                                                    |
| `params.bloom_threshold`   | number | No       | Threshold. 0 to 1.                                                                                    |
| `params.bloom_strength`    | number | No       | Strength. 0 to 2.                                                                                     |

</details>

<details>

<summary>Shape 21: action_id is split-text-browser</summary>

| Field                   | Type    | Required | Description                                                                    |
| ----------------------- | ------- | -------- | ------------------------------------------------------------------------------ |
| `action_id`             | string  | Yes      | Always `split-text-browser`.                                                   |
| `params.split_mode`     | string  | No       | Split Mode. One of: `separator`, `paragraph`, `bullets`, `lines`, `charCount`. |
| `params.separator`      | string  | No       | Separator                                                                      |
| `params.lines_per_part` | number  | No       | Lines per Part. 1 to 1000.                                                     |
| `params.chars_per_part` | number  | No       | Characters per Part. 1 to 100000.                                              |
| `params.trim_parts`     | boolean | No       | Trim Whitespace                                                                |
| `params.skip_empty`     | boolean | No       | Skip Empty Parts                                                               |
| `params.max_parts`      | number  | No       | Max Parts. 1 to 200.                                                           |

</details>

<details>

<summary>Shape 22: action_id is find-and-replace-text-browser</summary>

| Field                   | Type    | Required | Description                             |
| ----------------------- | ------- | -------- | --------------------------------------- |
| `action_id`             | string  | Yes      | Always `find-and-replace-text-browser`. |
| `params.find`           | string  | No       | Find                                    |
| `params.replace`        | string  | No       | Replace With                            |
| `params.case_sensitive` | boolean | No       | Case Sensitive                          |
| `params.whole_word`     | boolean | No       | Whole Word Only                         |
| `params.replace_all`    | boolean | No       | Replace All Occurrences                 |

</details>

<details>

<summary>Shape 23: action_id is concat-text-browser</summary>

| Field                   | Type    | Required | Description                   |
| ----------------------- | ------- | -------- | ----------------------------- |
| `action_id`             | string  | Yes      | Always `concat-text-browser`. |
| `params.separator`      | string  | No       | Separator                     |
| `params.prefix`         | string  | No       | Prefix                        |
| `params.suffix`         | string  | No       | Suffix                        |
| `params.wrap_each_part` | boolean | No       | Wrap Each Part                |
| `params.trim_parts`     | boolean | No       | Trim Each Part                |
| `params.skip_empty`     | boolean | No       | Skip Empty Parts              |
| `params.add_headers`    | boolean | No       | Add Input Name Headers        |

</details>

<details>

<summary>Shape 24: action_id is ken-burns-video</summary>

| Field                   | Type   | Required | Description                                                     |
| ----------------------- | ------ | -------- | --------------------------------------------------------------- |
| `action_id`             | string | Yes      | Always `ken-burns-video`.                                       |
| `params.duration`       | number | No       | Duration (s). 1 to 10.                                          |
| `params.zoom`           | number | No       | Zoom Level. 1 to 2.                                             |
| `params.zoom_direction` | string | No       | Zoom Direction. One of: `none`, `in`, `out`.                    |
| `params.pan_direction`  | string | No       | Pan. One of: `none`, `left`, `right`, `up`, `down`.             |
| `params.easing`         | string | No       | Easing. One of: `linear`, `ease-in`, `ease-out`, `ease-in-out`. |
| `params.fps`            | string | No       | FPS. One of: `24`, `30`, `60`.                                  |

</details>

<details>

<summary>Shape 25: action_id is stitch-videos</summary>

| Field                        | Type   | Required | Description                                                                                                           |
| ---------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `action_id`                  | string | Yes      | Always `stitch-videos`.                                                                                               |
| `params.transition`          | string | No       | Transition. One of: `none`, `fade`, `wipeleft`, `wiperight`.                                                          |
| `params.transition_duration` | number | No       | Transition Duration (s). 0.1 to 3.                                                                                    |
| `params.aspect_ratio`        | string | No       | Output Aspect Ratio. One of: `auto`, `21:9`, `16:9`, `3:2`, `4:3`, `5:4`, `1:1`, `4:5`, `3:4`, `2:3`, `9:16`, `9:21`. |
| `params.fit_mode`            | string | No       | Fit Mode. One of: `contain`, `cover`.                                                                                 |
| `params.background_mode`     | string | No       | Background Mode. One of: `solid`, `blur`.                                                                             |
| `params.blur_amount`         | number | No       | Blur Amount. 4 to 60.                                                                                                 |
| `params.background_color`    | string | No       | Background Color                                                                                                      |

</details>

<details>

<summary>Shape 26: action_id is split-video</summary>

| Field                      | Type    | Required | Description                                       |
| -------------------------- | ------- | -------- | ------------------------------------------------- |
| `action_id`                | string  | Yes      | Always `split-video`.                             |
| `params.split_mode`        | string  | No       | Split Mode. One of: `equal`, `duration`, `scene`. |
| `params.segments`          | number  | No       | Number of Segments. 2 to 10.                      |
| `params.segment_duration`  | number  | No       | Segment Duration (s). 0.5 to 120.                 |
| `params.scene_sensitivity` | number  | No       | Scene Sensitivity. 0.05 to 0.8.                   |
| `params.trim_handles`      | number  | No       | Trim Handles (s). -2 to 2.                        |
| `params.strip_audio`       | boolean | No       | Strip Audio                                       |

</details>

<details>

<summary>Shape 27: action_id is extract-video-frames</summary>

| Field                      | Type   | Required | Description                                              |
| -------------------------- | ------ | -------- | -------------------------------------------------------- |
| `action_id`                | string | Yes      | Always `extract-video-frames`.                           |
| `params.mode`              | string | No       | Frames. One of: `single`, `evenly`, `interval`, `scene`. |
| `params.time_percent`      | number | No       | Time (%). 0 to 100.                                      |
| `params.frame_count`       | number | No       | Frame Count. 1 to 24.                                    |
| `params.every_seconds`     | number | No       | Every (s). 0.25 to 60.                                   |
| `params.scene_sensitivity` | number | No       | Scene Sensitivity. 0.05 to 0.8.                          |
| `params.range`             | object | No       | Video Range (%)                                          |
| `params.range.min`         | number | Yes      | At least 0.                                              |
| `params.range.max`         | number | Yes      | At most 100.                                             |

</details>

<details>

<summary>Shape 28: action_id is color-grade-video</summary>

| Field               | Type   | Required | Description                 |
| ------------------- | ------ | -------- | --------------------------- |
| `action_id`         | string | Yes      | Always `color-grade-video`. |
| `params.contrast`   | number | No       | Contrast. 0.5 to 2.         |
| `params.saturation` | number | No       | Saturation. 0 to 2.         |
| `params.brightness` | number | No       | Brightness. -0.3 to 0.3.    |
| `params.gamma`      | number | No       | Gamma. 0.5 to 2.            |

</details>

<details>

<summary>Shape 29: action_id is video-to-frame-grid</summary>

| Field               | Type   | Required | Description                      |
| ------------------- | ------ | -------- | -------------------------------- |
| `action_id`         | string | Yes      | Always `video-to-frame-grid`.    |
| `params.rows`       | number | No       | Rows. 1 to 10.                   |
| `params.cols`       | number | No       | Columns. 1 to 10.                |
| `params.cell_width` | number | No       | Cell Width (px). 64 to 1024.     |
| `params.gap`        | number | No       | Gap Between Cells (px). 0 to 64. |
| `params.background` | string | No       | Background Color                 |

</details>

<details>

<summary>Shape 30: action_id is boomerang-video</summary>

| Field                  | Type    | Required | Description               |
| ---------------------- | ------- | -------- | ------------------------- |
| `action_id`            | string  | Yes      | Always `boomerang-video`. |
| `params.speed`         | number  | No       | Speed. 0.5 to 4.          |
| `params.include_audio` | boolean | No       | Include Audio             |

</details>

<details>

<summary>Shape 31: action_id is reverse-video</summary>

| Field               | Type   | Required | Description                                |
| ------------------- | ------ | -------- | ------------------------------------------ |
| `action_id`         | string | Yes      | Always `reverse-video`.                    |
| `params.audio_mode` | string | No       | Audio. One of: `strip`, `reverse`, `keep`. |

</details>

<details>

<summary>Shape 32: action_id is video-to-long-exposure</summary>

| Field                 | Type   | Required | Description                                         |
| --------------------- | ------ | -------- | --------------------------------------------------- |
| `action_id`           | string | Yes      | Always `video-to-long-exposure`.                    |
| `params.blend_mode`   | string | No       | Blend Mode. One of: `average`, `lighten`, `darken`. |
| `params.frame_stride` | number | No       | Frame Stride (sample every N frames). 1 to 30.      |
| `params.max_frames`   | number | No       | Max Frames to Sample. 10 to 2000.                   |

</details>

<details>

<summary>Shape 33: action_id is video-effect</summary>

| Field                     | Type   | Required | Description                                                                   |
| ------------------------- | ------ | -------- | ----------------------------------------------------------------------------- |
| `action_id`               | string | Yes      | Always `video-effect`.                                                        |
| `params.effect`           | string | No       | Effect. One of: `vignette`, `grain`, `pixelate`, `shake`, `chromatic`, `vhs`. |
| `params.vignette_angle`   | number | No       | Vignette Falloff. 0.1 to 1.4.                                                 |
| `params.grain_strength`   | number | No       | Grain Strength. 0 to 80.                                                      |
| `params.pixel_block_size` | number | No       | Block Size (px). 2 to 96.                                                     |
| `params.shake_amount`     | number | No       | Shake Amount (px). 1 to 64.                                                   |
| `params.chromatic_offset` | number | No       | Channel Offset (px). 1 to 30.                                                 |

</details>

<details>

<summary>Shape 34: action_id is color-filter-video</summary>

| Field                       | Type   | Required | Description                                                                                                                                      |
| --------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `action_id`                 | string | Yes      | Always `color-filter-video`.                                                                                                                     |
| `params.filter`             | string | No       | Filter. One of: `grayscale`, `sepia`, `invert`, `bw`, `posterize`, `solarize`, `clarendon`, `moon`, `nashville`, `noir`, `fade`, `crossprocess`. |
| `params.bw_threshold`       | number | No       | B\&W Threshold. 0 to 255.                                                                                                                        |
| `params.posterize_bits`     | number | No       | Posterize Bits. 1 to 8.                                                                                                                          |
| `params.solarize_threshold` | number | No       | Solarize Threshold. 0 to 255.                                                                                                                    |
| `params.grain`              | number | No       | Grain. 0 to 50.                                                                                                                                  |

</details>

<details>

<summary>Shape 35: action_id is speed-up-video</summary>

| Field               | Type    | Required | Description                   |
| ------------------- | ------- | -------- | ----------------------------- |
| `action_id`         | string  | Yes      | Always `speed-up-video`.      |
| `params.factor`     | number  | No       | Speed Factor (x). 1.25 to 10. |
| `params.keep_audio` | boolean | No       | Keep Audio (pitch-preserved)  |

</details>

<details>

<summary>Shape 36: action_id is slow-down-video</summary>

| Field               | Type    | Required | Description                                  |
| ------------------- | ------- | -------- | -------------------------------------------- |
| `action_id`         | string  | Yes      | Always `slow-down-video`.                    |
| `params.factor`     | number  | No       | Slow Factor (x). 1.25 to 6.                  |
| `params.keep_audio` | boolean | No       | Keep Audio (pitch-preserved)                 |
| `params.smoothing`  | string  | No       | Smoothing. One of: `off`, `blend`, `motion`. |

</details>

<details>

<summary>Shape 37: action_id is duplicate-video</summary>

| Field          | Type   | Required | Description               |
| -------------- | ------ | -------- | ------------------------- |
| `action_id`    | string | Yes      | Always `duplicate-video`. |
| `params.count` | number | No       | Copies. 1 to 10.          |

</details>

<details>

<summary>Shape 38: action_id is greenscreen-video</summary>

| Field                 | Type    | Required | Description                                              |
| --------------------- | ------- | -------- | -------------------------------------------------------- |
| `action_id`           | string  | Yes      | Always `greenscreen-video`.                              |
| `params.color_preset` | string  | No       | Background Preset. One of: `green`, `blue`, `custom`.    |
| `params.custom_color` | string  | No       | Custom Background Color                                  |
| `params.similarity`   | number  | No       | Similarity (how close to key color counts). 0.01 to 0.5. |
| `params.blend`        | number  | No       | Edge Blend (softness). 0 to 0.5.                         |
| `params.spill`        | boolean | No       | Spill Suppression                                        |

</details>

<details>

<summary>Shape 39: action_id is resize-video</summary>

| Field                      | Type   | Required | Description                                                                              |
| -------------------------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
| `action_id`                | string | Yes      | Always `resize-video`.                                                                   |
| `params.resolution`        | string | No       | Resolution. One of: `240`, `360`, `480`, `540`, `720`, `1080`, `1440`, `2160`, `custom`. |
| `params.custom_resolution` | number | No       | Custom Resolution (px). 144 to 2160.                                                     |

</details>

<details>

<summary>Shape 40: action_id is change-video-ar</summary>

| Field                    | Type   | Required | Description                                                                      |
| ------------------------ | ------ | -------- | -------------------------------------------------------------------------------- |
| `action_id`              | string | Yes      | Always `change-video-ar`.                                                        |
| `params.aspect_ratio`    | string | No       | Aspect Ratio. One of: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9`. |
| `params.fit`             | string | No       | Fit. One of: `crop`, `pad`.                                                      |
| `params.background_mode` | string | No       | Background. One of: `solid`, `blur`.                                             |
| `params.pad_color`       | string | No       | Pad Color                                                                        |
| `params.blur_amount`     | number | No       | Blur Amount. 4 to 60.                                                            |

</details>

<details>

<summary>Shape 41: action_id is split-audio-from-video</summary>

| Field                 | Type   | Required | Description                                        |
| --------------------- | ------ | -------- | -------------------------------------------------- |
| `action_id`           | string | Yes      | Always `split-audio-from-video`.                   |
| `params.audio_format` | string | No       | Audio Format. One of: `auto`, `m4a`, `mp3`, `wav`. |

</details>

<details>

<summary>Shape 42: action_id is merge-audio-into-video</summary>

| Field             | Type   | Required | Description                                     |
| ----------------- | ------ | -------- | ----------------------------------------------- |
| `action_id`       | string | Yes      | Always `merge-audio-into-video`.                |
| `params.duration` | string | No       | Duration. One of: `shortest`, `video`, `audio`. |

</details>

## Responses

### 201: Action run started.

| Field                    | Type                 | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------ | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run_id`                 | string               | Yes      | Run identifier. Pattern: `^run_\S+$`. Example: `run_abc123`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `type`                   | string               | Yes      | Run type. One of: `generation`, `technique`, `action`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `model`                  | object or null       | No       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `model.model_id`         | string               | Yes      | Model identifier. At least 1 character. Example: `t2i-flux-2-pro`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `technique`              | object or null       | No       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `technique.technique_id` | string               | Yes      | Technique identifier. Pattern: `^tech_\S+$`. Example: `tech_abcd1234`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `technique.name`         | string               | Yes      | Technique name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `action`                 | object or null       | No       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `action.action_id`       | string               | Yes      | Action identifier. One of: `color-grade-image-browser`, `overlay-image-browser`, `draw-image-browser`, `pixel-remover-image-browser`, `magic-eraser-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`, and 2 more. |
| `estimated_seconds`      | integer or null      | Yes      | At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `charged_cost`           | number               | Yes      | Cost in USD. For a generation run, the list price of this request's parameters before any plan discount, and an estimate for usage-priced models; when the request cannot be priced in time, the model's price at default settings. GET /runs/{run\_id} reports the settled amount once the run completes. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `poll_url`               | string (uri) or null | No       | URL to poll pending/running runs or fetch completed/failed run details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `project_id`             | string or null       | No       | Project identifier. Pattern: `^prj_\S+$`. Example: `prj_abc123`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `canvas_url`             | string (uri) or null | No       | Link to the project canvas. Hand this to the user as-is; a URL built from project\_id does not resolve.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `warnings`               | array of objects     | No       | Warnings for accepted input (unknown parameters and applied preprocessing changes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `warnings[].code`        | string               | Yes      | Stable warning code                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `warnings[].message`     | string               | Yes      | Human-readable warning message                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `warnings[].field`       | string               | No       | Feature or parameter the warning relates to                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

## Errors

Every error has the same body: `error.code`, `error.message`, and `error.fields` on validation errors. See [Errors](https://docs.flora.ai/api/platform/errors.md) for how to recover from each code.

| Status | Code                                         | Meaning                                                                             |
| ------ | -------------------------------------------- | ----------------------------------------------------------------------------------- |
| 400    | `invalid_json`, `input_validation_error`     | The body isn't valid JSON, or an input failed validation (`fields` lists each one). |
| 401    | `unauthorized`, `invalid_api_key`            | The API key is missing, invalid or revoked.                                         |
| 402    | `insufficient_credits`                       | The workspace balance is too low for this request.                                  |
| 403    | `forbidden`, `paid_plan_required`            | The key can't do this, or the workspace plan doesn't include it.                    |
| 404    | `not_found`                                  | The resource doesn't exist or isn't visible to this key.                            |
| 409    | `idempotency_duplicate`, `revision_conflict` | Duplicate `Idempotency-Key` or a stale `base_revision`.                             |
| 429    | `rate_limited`                               | Too many requests. Back off and retry.                                              |
| 500    | `unknown_error`, `internal_error`            | Something failed on FLORA's side. Retry with backoff.                               |
| 503    | `temporarily_unavailable`                    | Authorization is temporarily unavailable. Retry later.                              |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/api/reference/runs/createactionrun.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
