Model Endpoints

The fal client

The client libraries offer convenient ways to interact with fal endpoints. Currently we support the following platforms:

Our APIs are designed to be simple HTTP endpoints, so even if your platform of choice is not supported, you can still interact with them using standard HTTP requests. However, let us know if you would like to see support for a specific platform, we would love to hear your use case.


The fal client is available through the standard package manager for each supported language:

npm install --save @fal-ai/serverless-client


Navigate to our dashboard's keys page and generate a key from the UI.

All our clients expect FAL_KEY environment variable to be set by default.

export FAL_KEY=89733b28-••••••••

Initialize the client

In some environments, such as client-side JavaScript and native mobile apps, you will need to setup it up manually.

  credentials: "PASTE_YOUR_FAL_KEY_HERE", // or a function that returns a string

Subscribe to queue updates

The client offers a way for you to subscribe to queue updates. This is useful if you want to get notified when a function is done running, or if you want to get the logs as they are being generated.

import * as fal from "@fal-ai/serverless-client";
const result = await fal.subscribe("fal-ai/fast-lightning-sdxl", {
  input: {
    prompt: "a cute puppy",
  pollInterval: 500,
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS") { => log.message).forEach(console.log);

The onQueueUpdate callback will be called every time the queue status changes. The update object contains the queue status data as documented on the status types section.

Run functions

The client offers a way for you to run functions. This is useful if you want to run a function that execute fast and wait for the result.

import * as fal from "@fal-ai/serverless-client";
const result = await, {
  input: {
    prompt: "a cute puppy",

File uploads

Some APIs require you to pass a file URL as input. The good news is that the clients offer a way to easily upload files to our servers and get a URL back.


Some clients offer an auto-upload feature that will automatically upload the file for you. This is particularly useful for small files, such as images. For example, in JavaScript if the value of an input property is a File (or any Blob sub-type), the JS client will automatically upload the file and replace the value with the resulting URL. The same applies to Swift when using Data objects.

Note: auto-uploads are not supported in the Python client yet, but you can use the manual upload method instead.

Manual uploads

The auto-upload feature is just a convenience method built on top of our storage API, which means you can also handle file uploads yourself. That's useful in cases where you want to upload files before submission in order to provide a custom UI/UX for your users.

const file = /* reference to File object */;
const url = await;


Some endpoints support streaming, which allows you to get partial results as it is being generated. This is particularly useful for long running functions that produces intermediate results, such as Visual LLMs and Workflows with multiple steps.

The API should feel familiar to the other ones, but it will return a stream object that you can use to get all the events produced during the request. Here's an example with fal-ai/llavav15-13b:

import * as fal from "@fal-ai/serverless-client";
const stream = await"fal-ai/llavav15-13b", {
  input: {
    image_url: "",
    prompt: "Do you know who drew this painting?",
for await (const event of stream) {
  console.log("partial", event);
const result = await stream.done();
console.log("final result", result);

2023 © Features and Labels Inc.