JavaScript SDK

bun add @runflow-io/sdk
# or: npm install @runflow-io/sdk
# or: pnpm add @runflow-io/sdk

import { Runflow } from "@runflow-io/sdk";

const rf = new Runflow({ apiKey: process.env.RUNFLOW_API_KEY });

const dispatched = await rf.models.run("runflow/background-removal", {
  input: { image_url: "https://example.com/photo.jpg" },
});

const final = await rf.runs.wait(dispatched.id, {
  timeoutMs: 120_000,
  pollIntervalMs: 1500,
  onPoll: (run) => console.log(run.status_code),
});

console.log(final.output);

for await (const run of rf.runs.poll(dispatched.id)) {
  console.log(run.status_code);
}

import {
  defineTool,
  imageInput,
  textInput,
  imageOutput,
  Runflow,
} from "@runflow-io/sdk";

const sceneSwap = defineTool({
  id: "ai-scene",
  name: "Drop into a new scene",
  model: "google/nano-banana-pro/edit",
  inputs: {
    image: imageInput({ source: "runtime" }),
    prompt: textInput({
      source: "user",
      label: "Describe the scene",
      maxLength: 400,
    }),
    style: textInput({
      source: "preset",
      value: "Photoreal product photography, true colors preserved",
    }),
  },
  output: { image: imageOutput() },
  buildRequest: ({ image, prompt, style }) => ({
    input: {
      prompt: `Place the subject ${prompt}. ${style}.`,
      image_urls: [image],
    },
  }),
});

const rf = new Runflow({ apiKey: process.env.RUNFLOW_API_KEY });
const { output } = await rf.tools.run(sceneSwap, {
  image: "https://example.com/sneaker.png",
  prompt: "on a windswept rooftop at golden hour",
});
console.log(output.image);

const upscale = defineTool({
  id: "upscale",
  name: "Upscale",
  model: "topaz/upscale/image",
  inputs: { image: imageInput({ source: "runtime" }) },
  output: { image: imageOutput(), width: numberOutput(), height: numberOutput() },
  buildRequest: ({ image }) => ({ input: { image_url: image } }),
  extractOutput: (raw) => {
    const url = (raw as { image_urls: string[] }).image_urls[0];
    return { image: url, width: 4096, height: 4096 };
  },
});

const { runId, model } = await rf.tools.dispatch(sceneSwap, { image, prompt });
// later, from a webhook handler or a polling worker
const final = await rf.runs.wait(runId);

// browser
const rf = new Runflow({ baseUrl: "/api/runflow" });

interface RunflowConfig {
  apiKey?: string;            // server-side; sent as Authorization: Bearer
  baseUrl?: string;           // browser; usually "/api/runflow"
  apiBase?: string;           // override upstream base; default https://api.runflow.io
  requestTimeoutMs?: number;  // per-request timeout; default 30_000 ms
  headers?: Record<string, string>;
  fetch?: typeof fetch;       // custom fetch (useful in tests)
}

import { RunFailedError, RunTimeoutError, RunflowError } from "@runflow-io/sdk";

try {
  const run = await rf.runs.wait(id);
} catch (err) {
  if (err instanceof RunFailedError) {
    // Log err.run.error server-side; do not surface upstream messages to end users.
    console.error("run failed:", err.run.error);
  } else if (err instanceof RunTimeoutError) {
    console.error("run timed out:", err.runId);
  } else if (err instanceof RunflowError) {
    console.error("HTTP", err.status, err.code, err.message);
  } else {
    throw err;
  }
}

// app/api/runflow/[...path]/route.ts
import { runflowProxy } from "@runflow-io/proxy";

export const { GET, POST } = runflowProxy({
  apiKey: process.env.RUNFLOW_API_KEY!,
  authenticate: async (req) => {
    const session = await getSession(req);
    if (!session) return null; // returns 401
    return { userId: session.userId };
  },
});

import { runflowProxy } from "@runflow-io/proxy";

const handler = runflowProxy({ apiKey: process.env.RUNFLOW_API_KEY! });

// Hono
app.all("/api/runflow/*", (c) => handler(c.req.raw));

// Cloudflare Workers
export default { fetch: (req: Request) => handler(req) };

import { runflowProxyNode } from "@runflow-io/proxy/node";

app.use("/api/runflow", runflowProxyNode({
  apiKey: process.env.RUNFLOW_API_KEY!,
}));

runflowProxy({
  apiKey: process.env.RUNFLOW_API_KEY!,

  authenticate: async (req) => {
    const session = await getSession(req);
    if (!session) return null; // returns 401
    return { userId: session.userId, context: { plan: session.plan } };
  },

  rateLimit: async ({ auth }) => {
    const hits = await redis.incr(`rf:${auth?.userId}`);
    if (hits > 100) return { status: 429, message: "Slow down", retryAfter: 60 };
  },

  allowedModels: (auth) => {
    const plan = (auth?.context as { plan?: string })?.plan;
    return plan === "pro"
      ? ["runflow/background-removal", "google/nano-banana-pro/edit"]
      : ["runflow/background-removal"];
  },

  onRun: async ({ runId, model, auth }) => {
    await db.runs.insert({ runId, model, userId: auth?.userId });
  },
});