> 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/mcp/recipes/run-a-technique.md).
# Run your team's Technique
Find and run a saved FLORA Technique from your agent: list Techniques, read their inputs, run one with your images and text, and poll the result.
A Technique is a saved multi-step workflow (background swap, relight, upscale, a house style) built on the FLORA canvas. With [FLORA MCP](https://flora.ai/mcp), your agent finds one by name, fills its inputs and runs it, so you get the same treatment every time. Use this instead of [Generate an image or video](/mcp/recipes/generate.md) when your team has already captured the steps, prompts and models in a Technique.
**Works in:** Claude · Claude Code · ChatGPT · Codex · Cursor
**You need:** a connected client, a workspace with at least one Technique, and the Technique's `run_cost` per run (shown before you run; from free to several dollars)
**Use when:** someone on your team saved the workflow as a Technique, or you want to transform an image you already have with a fixed recipe.
**Don't use when:** you want a plain prompt-to-image run (use [generate](/mcp/recipes/generate.md)), or no Technique fits the job (don't force an unrelated one).
## Ask your agent
> Find my FLORA Technique for product background swaps and run it on this photo: \[paste the image URL]. Show me its inputs and the cost first, and wait for my OK before running it.
Open in Claude Open in ChatGPT
## What the agent does
{% hint style="info" %}
**Polling rule.** Save every `run_id`. Wait at least 15 seconds between polls, or 2 seconds per run for bigger batches (40 seconds for 20 runs). Then read every `run_id` in one `flora_list_generations` call (up to 20 per call). For example: `flora_list_generations({"run_ids": ["run_a", "run_b"]})`. For Technique runs, also pass `"technique_id"`. Polling faster returns `429` or cooldown errors with `retry_after_seconds`.
{% endhint %}
{% stepper %}
{% step %}
### Find the Technique
`flora_list_techniques` lists saved Techniques with their declared inputs, outputs and `run_cost` in US dollars. `query` filters by name:
```json
{
"workspace_id": "ws_123",
"query": "background"
}
```
If several match, the agent shows you the candidates. If you know the name, say it ("use the Clean Background v2 Technique") and the agent skips the search. To find Techniques your team has already used, `flora_list_technique_runs` lists past runs with their `technique_id`.
{% endstep %}
{% step %}
### Read its inputs
`flora_get_technique` returns the exact input IDs, their types (`text`, `imageUrl`, `videoUrl`, `audioUrl`, `documentUrl`, `model3dUrl`), whether each is `optional`, and any required aspect ratio or duration:
```json
{
"technique_id": "tech_abcd1234"
}
```
The input `id`s are the keys for the next step. The agent never guesses them from the display names.
{% endstep %}
{% step %}
### Get every media input to a FLORA URL
Two checks apply to media inputs (`imageUrl`, `videoUrl` and the other URL types):
1. **When you call `flora_run_technique`**, each media value must be a public `https://` URL: no `http://`, no `localhost` or private network address, and no `user:password@` in the URL. Anything else is rejected with `input_validation_error` before anything runs.
2. **While the run executes**, FLORA downloads media only from its own hosts (`media.flora.ai`, `ik.imagekit.io`) and a short storage allowlist (Google Cloud Storage, Amazon S3 object URLs, `fal.media`, `replicate.delivery`). A public URL on any other host passes the first check, then the run can fail partway through.
So pass FLORA URLs. For any other image (a website, a file on your computer), the agent uploads it first with `flora_create_asset` and uses the returned `url`; see [Upload your own images, video and files](/mcp/recipes/upload-files.md). Outputs from earlier FLORA runs (`https://media.flora.ai/…`) work as they are.
{% endstep %}
{% step %}
### Quote and wait for approval
Techniques have no quote call. The cost is the Technique's `run_cost` per run, times the number of runs. The agent tells you the total and waits for your OK.
{% endstep %}
{% step %}
### Run it
`flora_run_technique` takes the `technique_id` and an `inputs` map keyed by the input IDs. Every value is a string: text, or a media URL.
```json
{
"technique_id": "tech_abcd1234",
"inputs": {
"product_image": "https://media.flora.ai/…/mug.png",
"background": "warm oak table by a sunlit window"
}
}
```
It returns a `run_id`, and the run starts (and bills) right away. Every required input needs a value; an empty string counts as missing. Optional inputs can be left out.
In Claude, ChatGPT and other clients that show FLORA's in-chat views, the call runs immediately and also opens the FLORA action studio on that run; clicking **Apply** there runs the Technique again with the inputs on screen, and each Apply bills `run_cost` once. With `open_only: true`, the call runs nothing and bills nothing; the studio opens on the inputs and the first run starts when you click **Apply**. In those clients the studio waits for the run and hands the agent its status and outputs, so the agent doesn't need to poll. In clients without in-chat views (Claude Code, Codex, Cursor), the agent polls as in the next step.
{% endstep %}
{% step %}
### Poll with the technique\_id
Technique runs are read with `flora_list_generations`, passing the same `technique_id`. It applies to every ID in the call, so poll runs of one Technique together. Wait at least 15 seconds between polls of the same runs, or 2 seconds per run when there are more than 7 (40 seconds for 20):
```json
{
"run_ids": ["run_t1", "run_t2"],
"technique_id": "tech_abcd1234"
}
```
When `status` is `completed`, `outputs[]` holds each output's `type` and `url`. For 3D outputs, `flora_view_model3d` with the `run_id` and `technique_id` opens an inspector.
{% endstep %}
{% endstepper %}
## Where it bills and where the outputs go
`flora_run_technique` takes no `workspace_id` or `project_id`:
* **Billing:** the run bills the workspace your connection resolves to. With an API key, that's the key's workspace. With an OAuth sign-in (Claude, ChatGPT and most clients), it's the earliest-joined of your workspaces that has API access. **An OAuth connection can't choose another workspace for Techniques:** there's no argument for it, and reconnecting doesn't change it. To bill a specific workspace, connect with an API key created in that workspace (see [authentication](/mcp/authentication.md)).
* **Outputs:** each run returns its outputs on the run itself (`outputs[].url`, and `asset_id` for media). FLORA also keeps the run in a private project named after the Technique, in the billed workspace, created on the first run and reused after that. `flora_list_technique_runs` shows each run's `project_id`.
## Run it on 20 images
The same flow, at batch size. 20 photos at a `run_cost` of $0.25 is $5.00; the agent says so and waits for your OK first.
1. **Upload all 20 in one call.** `flora_create_asset` with `sources` (up to 25 entries) and the photos' URLs, or `"source": "signed-url"` entries for local files. Finish any signed-url entries with one `flora_complete_asset` call and `asset_ids`. Each asset's `url` becomes an input value. See [Upload many files at once](/mcp/recipes/upload-files.md#upload-many-files-at-once).
2. **Run one first and check which workspace it billed.** The agent runs the first photo, then reads it back with `flora_list_technique_runs` (`{ "technique_id": "tech_abcd1234", "limit": 1 }`) and checks the run's `workspace_id`. If it's not the workspace you meant, it stops there (see [Where it bills](#where-it-bills-and-where-the-outputs-go)).
3. **Note the time, then start the other 19.** `flora_run_technique` runs one input set per call, so the agent makes 19 more calls, in parallel, without `open_only`, and saves each `run_id` next to its photo. Each call runs exactly once.
**Don't press Apply during a batch.** In Claude and ChatGPT, each call can open its own action studio, and every **Apply** in a studio starts and bills another run. The agent also never uses `open_only: true` for a batch (that would need an Apply per photo). The runs the calls started are the whole batch.
4. **Poll all 20 in one call, every 40 seconds.** The wait between polls is 2 seconds per run with a 15-second minimum, so 20 runs means one `flora_list_generations` call every 40 seconds, with all 20 `run_ids` and the `technique_id`:
```json
{
"run_ids": ["run_t01", "run_t02", "run_t03", "run_t04", "run_t05", "run_t06", "run_t07", "run_t08", "run_t09", "run_t10", "run_t11", "run_t12", "run_t13", "run_t14", "run_t15", "run_t16", "run_t17", "run_t18", "run_t19", "run_t20"],
"technique_id": "tech_abcd1234"
}
```
Polling sooner returns `429` entries or a cooldown error with `retry_after_seconds`. A single call takes at most 20 IDs, so 40 runs is two calls every 40 seconds. In clients with FLORA's in-chat views, each run's studio reports back on its own, and the agent only needs to poll runs it hasn't heard about.
5. **Recover after a timeout.** If a `flora_run_technique` call times out, the run may have started anyway, and calling again bills again. Before re-running, the agent lists recent runs of that Technique:
```json
{
"technique_id": "tech_abcd1234",
"limit": 50
}
```
`flora_list_technique_runs` returns runs newest first with `run_id`, `status`, `created_at` and `outputs`. Any run created after the batch started whose `run_id` isn't in the agent's list came from a timed-out call. The list doesn't show inputs, so if the count doesn't settle which photos are missing, the agent asks you before re-running anything.
6. **Retry only real failures.** Failed runs aren't charged, but every re-run bills `run_cost` again. The agent checks `error_message` and re-runs just that photo if the cause was temporary.
## Check it worked
* Each run reaches `status: "completed"` with the outputs the Technique declares.
* `flora_list_technique_runs` with the `technique_id` shows the run, its status and its cost.
## If it fails
| Symptom | Cause | Fix |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `Unknown technique input "…"; declared inputs: …` | An input key doesn't match the Technique's input IDs | Rebuild `inputs` from `flora_get_technique` and retry once. |
| `input_validation_error`: `Input "…": URL must use https://` (or names a private host) | A media input isn't a public HTTPS URL | Upload the file with `flora_create_asset` and pass its `url`. |
| Run fails soon after starting when a media input is on an outside host | FLORA only downloads media from its own hosts and its storage allowlist | Upload the file with `flora_create_asset` and run again with its `url`. |
| `input_validation_error`: `Missing required input "…"` | A required input was left out or sent as `""` | Give it a value from the user. |
| Run not found while polling | `technique_id` was left out of `flora_list_generations` | Add the same `technique_id` to the poll call. |
| `insufficient_credits` or a `BILLING_*` code | Not enough balance in the workspace | Stop and relay the message. Don't retry. |
| Nothing ran after the studio opened | The call used `open_only: true` and you haven't clicked **Apply** | Click **Apply** in the studio, or call again without `open_only`. |
| The run billed a workspace you didn't expect | `flora_run_technique` has no `workspace_id`; it bills the connection's workspace | See [Where it bills and where the outputs go](#where-it-bills-and-where-the-outputs-go). |
To learn what Techniques are and how to build one, see [Techniques](/nodes/techniques.md) and the [Technique Builder](/nodes/technique-builder.md). Every argument is in the [tools reference](/mcp/tools/techniques-and-actions.md#flora_run_technique).
---
# 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/mcp/recipes/run-a-technique.md?ask=&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.