TypeScript

The @flora-ai/flora SDK is a thin, type-safe wrapper around the FLORA REST API. It runs in Node 18+ and the browser (server-only — never ship an API key to the client).

Install

npm install @flora-ai/flora
# pnpm add @flora-ai/flora
# yarn add @flora-ai/flora

Configure

Set your API key in the environment:

export FLORA_API_KEY="ak_XXXX"

The SDK reads it automatically:

import { FloraClient } from "@flora-ai/flora"

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

You can also pass the key explicitly: new FloraClient({ apiKey: 'ak_XXXX' }).

First run, end to end

The full discover → run → poll loop in one snippet:

import { FloraClient } from "@flora-ai/flora"

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

// 1. List your Techniques
for await (const technique of client.techniques.list()) {
  console.log(technique.slug, technique.name)
}

// 2. Inspect a specific Technique's inputs
const technique = await client.techniques.retrieve({ techniqueId: "thumbnail-v3" })
console.log(technique.inputs)

// 3. Start a run
const run = await client.techniques.runs.create({
  techniqueId: "thumbnail-v3",
  inputs: [{ id: "prompt", type: "text", value: "Smart living, simple — warm minimalism" }],
  mode: "async",
})

// 4. Poll until completion
let status = run.status
let result = run
while (status === "pending" || status === "running") {
  await new Promise((r) => setTimeout(r, 2000))
  result = await client.techniques.runs.retrieve({ techniqueId: "thumbnail-v3", runId: run.run_id })
  status = result.status
}

if (status === "completed") {
  for (const output of result.outputs) {
    console.log(output.url)
  }
} else {
  console.error("Run failed:", result.error_message)
}

Pagination

list() returns an async iterator that auto-paginates:

for await (const technique of client.techniques.list({ limit: 10 })) {
  // iterates across all pages
}

For a single page:

const page = await client.techniques.list({ limit: 10 })
console.log(page.data, page.hasNextPage())

Idempotency

Pass idempotency_key on any mutation that you might retry:

const run = await client.techniques.runs.create({
  techniqueId: 'thumbnail-v3',
  inputs: [...],
  mode: 'async',
  idempotency_key: `q3-thumb-${marketCode}`,
});

Same key + same body = same run. See Idempotency for the full semantics.

Errors

The SDK throws typed errors with status codes and request IDs:

import { FloraClient, FloraError } from "@flora-ai/flora"

try {
  await client.techniques.runs.create({
    techniqueId: "thumbnail-v3",
    inputs: [],
    mode: "async",
  })
} catch (err) {
  if (err instanceof FloraError) {
    // Typed per status: Flora.BadRequestError, Flora.TooManyRequestsError, …
    const apiError = (err.body as { error?: { code?: string; message?: string } } | undefined)
      ?.error
    console.error(err.statusCode, apiError?.code, apiError?.message, err.requestId)
  } else {
    throw err
  }
}

See Errors for every code and recovery guidance.

What’s next

• Authentication — keys, rotation, security.
• Recipes — common end-to-end patterns in code.
• API Reference — every method, parameter, and response type.