fal.ai JS Client

Every realtime session follows a consistent lifecycle regardless of the underlying protocol. This allows applications to use a single status indicator for multiple models.

States:

• "opening": The initial state during negotiation.
• "live": The session is active and the transport is ready.
• "failed": A terminal state indicating a transport error. Note: failed takes precedence over closed if a session dies.
• "closed": A terminal state indicating the session was intentionally ended.

Diagnostics: For fine-grained details (like progress or specific error messages), use the onDiagnostic callback. Diagnostics use a RealtimeDiagnostic type with kind values of "progress", "warning", or "failure".

When configuring proxyUrl as an object in fal.config(), you can control which environments use the proxy via the when property. The when property accepts:

• "browser": Only uses the proxy in environments with a DOM window (this is the default behavior when using a string URL).
• "always": Uses the proxy in every runtime (Node, Electron, Bun, etc.).
• (env) => boolean: A custom predicate function. The env argument is an object: { isBrowser: boolean }.

// Example: Routing through proxy in browser OR Electron renderer process
fal.config({
  proxyUrl: {
    url: "/api/fal/proxy",
    when: ({ isBrowser }) => isBrowser || (typeof process !== "undefined" && process.type === "renderer"),
  },
});

Realtime sessions provide two standardized callbacks for inbound information, ensuring compatibility across different extensions:

• onMedia(stream): Fires once per inbound MediaStream. Use this to attach remote video/audio to a UI element.
• onData(raw): Fires once per message on the extension's data channel. The raw argument is a string; the extension is responsible for the data format, so you must parse it (e.g., JSON.parse(raw)).

Both callbacks are optional and are designed to be non-breaking; an error thrown inside a handler will be swallowed to prevent crashing the connection.

const session = fal.realtime.open(wma("fal-ai/wma-outstream"), {
  onMedia: (stream) => {
    videoEl.srcObject = stream;
  },
  onData: (raw) => setScore(JSON.parse(raw)),
});

To safeguard sensitive credentials by routing client requests through your own server, install the @fal-ai/server-proxy package using npm.

npm install --save @fal-ai/server-proxy

To use the fal.ai JavaScript/TypeScript client, import fal from @fal-ai/client and call fal.config() to provide your credentials. You can pass your FAL_KEY directly or rely on environment variables for auto-configuration.

Security Note: For client-side applications, use the @fal-ai/server-proxy package to ensure your credentials remain protected.

import { fal } from "@fal-ai/client";

fal.config({
  // Can also be auto-configured using environment variables:
  credentials: "FAL_KEY",
});

To use the proxy with the Next.js App Router:

1. Create an API route (e.g., app/api/fal/proxy/route.ts).
2. Import route from @fal-ai/server-proxy/nextjs and export the HTTP methods GET, POST, and PUT from it.
3. Set the FAL_KEY environment variable on your server with a valid API Key.

import { route } from "@fal-ai/server-proxy/nextjs";

export const { GET, POST, PUT } = route;

The @fal-ai/client library allows you to consume fal apps in Web, Node.js, and React Native environments. It is a lightweight wrapper around fetch that provides type safety by mapping Python function outputs to JavaScript types.

To use it, install the package, configure your credentials using fal.config, and then execute functions using fal.run(functionId).

import { fal } from "@fal-ai/client";

// 1. Configure credentials
fal.config({
  // Can also be auto-configured using environment variables:
  credentials: "FAL_KEY",
});

// 2. Execute a function
const result = await fal.run("user/app-alias");

To use the proxy with the Next.js Page Router:

1. Create an API route (e.g., pages/api/fal/proxy.ts).
2. Re-export the proxy handler as the default export from @fal-ai/server-proxy/nextjs.
3. Set the FAL_KEY environment variable on your server with a valid API Key.

export { handler as default } from "@fal-ai/server-proxy/nextjs";

To use the proxy with an Express application:

1. Ensure your app supports JSON payloads using express.json() or body-parser.
2. Import falProxy from @fal-ai/server-proxy/express.
3. Use app.all() to register the proxy route. If your client is external to the Express app, you must include CORS middleware (e.g., cors()) in the route handler.
4. Set the FAL_KEY environment variable on your server with a valid API Key.

import * as falProxy from "@fal-ai/server-proxy/express";

app.use(express.json());

app.all(
  falProxy.route, // '/api/fal/proxy' or your own path
  cors(), // required if external clients will use the proxy
  falProxy.handler,
);

During the connection phase, the Lucy extension reports connection states as progress details. The LucyConnectionState type includes:

• negotiating: The initial phase where SDP exchange is occurring.
• RTCPeerConnectionState: The standard WebRTC connection states (e.g., connected, disconnected, failed, closed).

These states are reported via context.diagnostic with kind: "progress" and phase: "connection-state" to help distinguish Lucy-specific signaling progress from general protocol lifecycle events.