Getting Started

FLORA API

Questions or need help getting started? Book an API onboarding call — we’re happy to walk you through setup and answer questions.

API access requires a paid FLORA subscription. Manage your plan at app.flora.ai.

The FLORA API lets you interact with your creative canvas programmatically. Let’s walk through an example of how to use it to look up a technique, inspect its inputs, submit a run, and poll for results.

Base URL: https://app.flora.ai/api/v1

Step 1: Create your API key

1. Sign in to FLORA.
2. Open Settings > API Keys, or use this link.
3. Click Create API Key, give it a name, and copy the secret immediately. It is shown only once.
4. You can only have one active key at a time. To rotate keys, revoke the old key first.

Use the key in every request:

Authorization: Bearer sk_live_XXXX

Step 2: Find or list a technique

Every technique has a slug: a short, URL-safe identifier. You can find it in the URL when you open a technique in FLORA:

https://app.flora.ai/api/v1/techniques/portrait-enhancer

You can also list techniques:

curl "https://app.flora.ai/api/v1/techniques?limit=5" \
  -H "Authorization: Bearer sk_live_XXXX"

Any technique you’ve built with the technique builder or that is available in your techniques dashboard can be used via the API. Techniques themselves are authored in FLORA’s visual workflow editor — the API runs them by slug, it doesn’t create or edit them.

Step 3: Look up a technique’s inputs

Before running a technique, fetch its details to see the required inputs, expected outputs, and per-run cost in USD:

curl https://app.flora.ai/api/v1/techniques/{slug} \
  -H "Authorization: Bearer sk_live_XXXX"

Example response:

{
  "technique_id": "abc123...",
  "name": "Portrait Enhancer",
  "description": "Enhance portrait photos with AI",
  "run_cost": 0.05,
  "inputs": [
    { "id": "input_image", "name": "Input Image", "type": "imageUrl" }
  ],
  "outputs": [
    { "id": "output_image", "name": "Output Image", "type": "imageUrl" }
  ]
}

Use the inputs array to build your run request. Match each input id and type exactly.

Public API ID prefixes

Most create/list requests require public IDs returned by the API:

| Resource | Prefix | Where to get it | | --------- | -------- | ----------------------------------- | | Workspace | ws_ | GET /workspaces | | Project | prj_ | GET /projects?workspace_id=ws_... | | Technique | tech_ | GET /techniques | | Run | run_ | Create run responses | | Asset | asset_ | Create/list asset responses |

If an endpoint returns input_validation_error, check both the field name and the ID prefix in the error response.

Step 4: Create a run

curl -X POST https://app.flora.ai/api/v1/techniques/{slug}/runs \
  -H "Authorization: Bearer sk_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      { "id": "input_image", "type": "imageUrl", "value": "https://example.com/photo.jpg" }
    ],
    "mode": "async"
  }'

Response:

{
  "run_id": "j57abc...",
  "created_at": 1710000000000,
  "status": "pending",
  "progress": 0,
  "poll_url": "https://app.flora.ai/api/v1/techniques/{slug}/runs/j57abc..."
}

Step 5: Poll for results

curl https://app.flora.ai/api/v1/techniques/{slug}/runs/{runId} \
  -H "Authorization: Bearer sk_live_XXXX"

Poll every 2–5 seconds until status is completed or failed.

{
  "run_id": "j57abc...",
  "status": "completed",
  "progress": 100,
  "created_at": 1710000000000,
  "started_at": 1710000001000,
  "completed_at": 1710000030000,
  "charged_cost": 0.05,
  "outputs": [
    {
      "output_id": "output_image",
      "type": "imageUrl",
      "url": "https://ik.imagekit.io/flora/..."
    }
  ]
}

Output URLs are long-lived but not permanent. Download anything you need to keep — don’t rely on a returned URL still resolving weeks or months later.

Core endpoints

| Method | Path | Description | | ------ | --------------------------------------- | ------------------------------------------------------------ | | GET | /workspaces | List workspaces available to your API key | | GET | /projects?workspace_id={workspace_id} | List projects in a workspace | | POST | /assets | Create an asset or reserve a signed upload | | GET | /models?type=image | List available models | | GET | /techniques/{slug} | Get technique details, inputs, outputs, and per-run USD cost | | POST | /techniques/{slug}/runs | Create and start a technique run | | GET | /techniques/{slug}/runs/{runId} | Poll technique run status and results |

Create run request fields

| Field | Required | Notes | | ----------------- | -------- | ----------------------------------------------------------------------- | | inputs | Yes | Must match the technique’s expected inputs: count, IDs, and types | | inputs[].id | Yes | Input identifier from the technique’s inputs array | | inputs[].type | Yes | Usually imageUrl, videoUrl, or text | | inputs[].value | Yes | URL for images/videos, or text content | | mode | Yes | Use "async" | | idempotency_key | No | Prevents duplicate runs on retry; the same key returns the existing run |

Input media URL restrictions

Only HTTPS URLs are accepted (https://, not http://).

Supported hosts include FLORA media, Google Cloud Storage, Amazon S3, and ImageKit URLs.

Run statuses

| Status | Meaning | | ----------- | ---------------------------------------- | | pending | Queued | | running | In progress; progress shows 0–100% | | completed | Done; check outputs and charged_cost | | failed | Check error_code and error_message |

Errors

Errors return an object like { "error": { "code": "...", "message": "..." } }. Validation errors may also include fields, for example { "field": "workspace_id", "message": "Workspace identifier must start with ws_" }.

| Code | HTTP | Meaning | | ------------------------ | ---- | --------------------------------------------- | | unauthorized | 401 | Missing auth header | | invalid_api_key | 401 | Bad or revoked key | | invalid_json | 400 | Malformed request body | | input_validation_error | 400 | Wrong inputs for this technique | | not_found | 404 | Bad resource ID, technique slug, or run ID | | insufficient_credits | 402 | Workspace balance is too low to start the run | | forbidden | 403 | Your key cannot perform this action |

Problems?

If you need help, send us the request ID from the response headers. You can capture headers with curl -i:

curl -i https://app.flora.ai/api/v1/techniques/cctv-cam \
  -H "Authorization: Bearer sk_live_XXXX"

Include the request ID, the endpoint you called, and the approximate time of the request when you contact support.