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-clientNavigate 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-••••••••In some environments, such as client-side JavaScript and native mobile apps, you will need to setup it up manually.
fal.config({
credentials: "PASTE_YOUR_FAL_KEY_HERE", // or a function that returns a string
});Although the client works in a browser environment, it is not recommended to keep the credentials in the browser. Instead, you should use a server-side proxy to handle the credentials. Check out our server-side guide for guidance.
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) => {
console.log(update.status);
if (update.status === "IN_PROGRESS") {
update.logs.map((log) => log.message).forEach(console.log);
}
},
});
console.log(result.url);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.
The client contains all type definitions built-in, so regardless if you use TypeScript or JavaScript, you will get type hints and autocompletion.
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 fal.run(FUNCTION_ID, {
input: {
prompt: "a cute puppy",
},
});
console.log(result);The run method is a convenience for short running functions, it will simply run the function and wait for the result. For long running functions, such as ML flows, it is recommended to use the queue instead.
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.
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 fal.storage.upload(file);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.stream("fal-ai/llavav15-13b", {
input: {
image_url: "https://llava-vl.github.io/static/images/monalisa.jpg",
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);