proxy

fal.ai proxy library

Introduction

The @fal-ai/server-proxy library enables you to route client requests through your own server, therefore safeguarding sensitive credentials. With built-in support for popular frameworks like Next.js and Express, setting up the proxy becomes a breeze.

Install the proxy library:

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

Next.js page router integration

For Next.js applications using the page router:

1. Create an API route in your Next.js app, as a convention we suggest using pages/api/fal/proxy.js (or .ts if you're using TypeScript):
2. Re-export the proxy handler from the library as the default export:

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

3. Ensure you've set the FAL_KEY as an environment variable in your server, containing a valid API Key.

Next.js app router integration

For Next.js applications using the app router:

1. Create an API route in your Next.js app, as a convention we suggest using app/api/fal/proxy/route.js (or .ts if you're using TypeScript):

2. Re-export the proxy handler from the library as the default export:

   import { route } from "@fal-ai/server-proxy/nextjs";
   
   export const { GET, POST, PUT } = route;

3. Ensure you've set the FAL_KEY as an environment variable in your server, containing a valid API Key.

Express integration

For Express applications:

1. Make sure your app supports JSON payloads, either by using express.json() (recommended) or body-parser:

   app.use(express.json());

2. Add the proxy route and its handler. Note that if your client lives outside of the express app (i.e. the express app is solely used as an external API for other clients), you will need to allow CORS on the proxy route:

   import * as falProxy from "@fal-ai/server-proxy/express";
   
   app.all(
     falProxy.route, // '/api/fal/proxy' or you can use your own
     cors(), // if external clients will use the proxy
     falProxy.handler,
   );

3. Ensure you've set the FAL_KEY as an environment variable in your server, containing a valid API Key.

Client configuration

Once you've set up the proxy, you can configure the client to use it:

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

fal.config({
  proxyUrl: "/api/fal/proxy", // or https://my.app.com/api/fal/proxy
});

Now all your client calls will route through your server proxy, so your credentials are protected.

By default, the proxy middleware only runs in browser environments — requests made from Node, Electron, Bun, or edge/worker runtimes are sent directly to the fal API. To opt into the proxy in these runtimes, pass an object instead of a string:

fal.config({
  proxyUrl: {
    url: "/api/fal/proxy",
    when: "always",
  },
});

when accepts:

• "browser" — only in environments with a DOM window (default).

• "always" — in every runtime.

• (env) => boolean — a custom predicate. env is { isBrowser: boolean }, so you can layer your own checks — for example, routing through the proxy only from an Electron renderer process:

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

More information

For a deeper dive into the proxy library and its capabilities, explore the official documentation.