Fal.ai

Overview

Fal.ai is the generative media platform for developers, with 600+ AI models for image, video, voice, and audio generation. With the Fal.ai integration in SquadOS, your agents can invoke generative content models synchronously or asynchronously, upload media files as inputs, query model pricing, and monitor queue job status — all from conversations and automated workflows.

• Official website: https://fal.ai/
• Composio documentation: docs.composio.dev/toolkits/fal_ai

Authentication

This tool uses API key (API_KEY) to connect.

You will need the following fields:

Field	Required	Description
api_key	Yes	API key generated in the Fal.ai dashboard, used to authenticate all inference and queue management requests.

How to get credentials

1. Go to fal.ai/login and create an account or log in with GitHub or Google.
2. In the left sidebar of the dashboard, click API Keys (or navigate directly to fal.ai/dashboard/keys).
3. Click Add Key.
4. Give the key a name (e.g., squados) and click Create Key.
5. Copy the generated key and store it in a safe place — it will not be shown again.

Tip

Create a dedicated key for SquadOS. This way you can revoke access for this integration without affecting other tools or projects that use the same Fal.ai account.

How to connect in SquadOS

1. Go to Tools in the side menu (/admin/tools).
2. Open the Available tab and search for Fal.ai.
3. Click the card to open the details modal and hit Connect.
4. You’re taken to the secure connection page hosted by Composio, where you enter the API key obtained above.
5. Once done, you’re sent back to SquadOS with the account connected and the tool available to your agents. (Connection-flow details in Organization Tools.)

Available actions

Cancel Queue Request

FAL_AI_CANCEL_QUEUE_REQUEST

Tool to cancel a queued or in-progress request in fal.ai’s queue system. Use when you need to stop a request before it completes. Note that cancellation only succeeds if the request hasn’t started processing; if already completed, returns an error status. Even with successful cancellation, the request may still execute if it was near the front of the queue.

Input parameters

Name	Type	Required	Description
model_id	string	Yes	The model identifier in namespace/name format (e.g., fal-ai/flux, fal-ai/fast-sdxl).
request_id	string	Yes	The unique identifier of the queued request to cancel.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Estimate Pricing

FAL_AI_ESTIMATE_PRICING

Tool to estimate pricing for fal.ai model endpoints. Use when you need to calculate expected costs for API calls or unit-based usage across one or more endpoints.

Input parameters

Name	Type	Required	Description
endpoints	object	Yes	Map of endpoint IDs (e.g., fal-ai/flux/dev) to their quantity specifications. Use call_quantity for historical_api_price or unit_quantity for unit_price.
estimate_type	string ("historical_api_price" | "unit_price")	Yes	Estimation method: historical_api_price for call-based estimates or unit_price for unit-based estimates.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get JWKS for Webhook Verification

FAL_AI_GET_JWKS

Tool to retrieve public keys for webhook signature verification. Returns a JSON Web Key Set containing ED25519 public keys. Use when you need to verify webhook signatures from fal.ai. The keys are cacheable but should be refreshed at least every 24 hours.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get Models

FAL_AI_GET_MODELS

Tool to discover and search fal.ai model endpoints. Use when you need to list all models, find specific models by ID, or search by category/query. Supports pagination and optional expansion of OpenAPI schemas.

Input parameters

Name	Type	Required	Description
q	string	No	Free-text search query. Filters models by name, description, or category. Use for broad text-based searches.
limit	integer	No	Maximum number of items to return. Actual maximum depends on query type.
cursor	string	No	Pagination cursor from previous response. Encodes page number for fetching next page.
expand	string	No	Fields to expand in response. Supports openapi-3.0 to include full OpenAPI schema for each model.
status	string ("active" | "deprecated")	No	Filter models by status. Use active for currently supported models or deprecated for outdated ones. Omit to include all statuses.
category	string	No	Filter models by specific category. Use exact category names like text-to-image, image-to-video, etc.
endpoint_id	string	No	Specific endpoint ID(s) to retrieve. Accepts a single string or array of strings (1–50 models). Use to filter models by their unique identifiers.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get Model Pricing

FAL_AI_GET_PRICING

Tool to retrieve unit pricing for model endpoints. Returns pricing information including unit price, billing unit, and currency. Use when you need to check costs for specific fal.ai models.

Input parameters

Name	Type	Required	Description
endpoint_id	string	Yes	Filter by specific endpoint ID(s). Accepts 1–50 endpoint IDs. Can be a single endpoint ID string or a list of endpoint IDs. Examples: fal-ai/flux/dev or ['fal-ai/flux/dev', 'fal-ai/flux/pro'].

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get Queue Request Result

FAL_AI_GET_QUEUE_REQUEST_RESULT

Tool to retrieve the final result of a completed queue request. Use when you need to get the output of a model request that was submitted to the queue and has finished processing. Only works after request status transitions to COMPLETED.

Input parameters

Name	Type	Required	Description
model_id	string	Yes	The model identifier in namespace/name format (e.g., fal-ai/flux, fal-ai/fast-sdxl).
request_id	string	Yes	The unique identifier of the queued request to retrieve results for.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Check Queue Request Status

FAL_AI_QUEUE_GET_STATUS

Tool to check the status of a queued request in fal.ai. Use when you need to monitor the progress of an async request. Returns different information based on status: queue position when IN_QUEUE, logs when IN_PROGRESS or COMPLETED.

Input parameters

Name	Type	Required	Description
logs	integer	No	Set to 1 to enable log retrieval in the response; disabled by default for performance.
model_id	string	Yes	Model identifier in namespace/name format (e.g., fal-ai/fast-sdxl).
request_id	string	Yes	Unique identifier returned after submitting a request.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Stream Request Status Updates

FAL_AI_QUEUE_GET_STATUS_STREAM

Tool to stream request status updates via SSE. Use when you need real-time updates on a queued request’s processing state.

Input parameters

Name	Type	Required	Description
logs	integer	No	Set to 1 to include detailed logging information in the stream, 0 or omit to exclude logs.
model_id	string	Yes	The model identifier (e.g., fal-ai/fast-lightning-sdxl).
request_id	string	Yes	The unique identifier returned when submitting a request.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Run Model (Sync)

FAL_AI_RUN_MODEL_SYNC

Tool to invoke a fal.ai model synchronously via fal.run, generating new content (images, audio, video, or other model outputs) hosted at fal.ai CDN URLs in the response. Each call executes paid inference on fal.ai — it consumes the connected account’s credit balance and is billed per request, so it is NOT a read-only operation. Use when you need a single-shot result and the model is fast enough to return inline — the request blocks until the model finishes and returns the generated output directly. For long-running jobs, parallel invocations, or anything production-grade, prefer SUBMIT_ASYNC_JOB (queue.fal.run) which adds persistence, retries, and webhooks; both produce the same kind of newly-generated, persistently-hosted output and are billed identically.

Input parameters

Name	Type	Required	Description
input	object	Yes	Model-specific input payload posted as the JSON request body. Fields depend on the chosen model — for example image generation models typically expect a prompt (and optionally image_size, num_inference_steps, etc.). Refer to the model’s OpenAPI schema (see GET_MODELS with expand=openapi-3.0) for the full field list.
model_id	string	Yes	The model identifier in namespace/name format (e.g., fal-ai/flux/schnell, fal-ai/fast-sdxl). Slashes in the model id are preserved in the URL path.
runner_hint	string	No	Optional session affinity hint to route subsequent requests to the same runner. Sent as the X-Fal-Runner-Hint header.
timeout_seconds	integer	No	Optional server-side execution deadline in seconds. Sent as the X-Fal-Request-Timeout header.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Submit Async Inference Job

FAL_AI_SUBMIT_ASYNC_JOB

Tool to submit an asynchronous inference job to fal.ai’s queue (queue.fal.run). Use when you want to run a model without blocking — fal.ai persists the request, auto-scales runners, and you fetch the result later via the returned request_id (use QUEUE_GET_STATUS to poll, GET_QUEUE_REQUEST_RESULT to retrieve, CANCEL_QUEUE_REQUEST to abort, QUEUE_GET_STATUS_STREAM to receive SSE updates). Supports an optional webhook_url that fal.ai will POST results to on completion.

Input parameters

Name	Type	Required	Description
input	object	Yes	Model-specific input payload posted as the JSON request body. Fields depend on the chosen model — for example image generation models typically expect a prompt (and optionally image_size, num_inference_steps, etc.). Refer to the model’s OpenAPI schema (see GET_MODELS with expand=openapi-3.0) for the full field list.
model_id	string	Yes	The model identifier in namespace/name format (e.g., fal-ai/flux/schnell, fal-ai/fast-sdxl). Slashes in the model id are preserved in the URL path.
no_retry	boolean	No	Set to true to disable fal.ai’s automatic retries on transient runner errors. Sent as the X-Fal-No-Retry header when true.
priority	string ("normal" | "low")	No	Optional queue priority hint. Sent as the X-Fal-Queue-Priority header.
runner_hint	string	No	Optional session affinity hint to route subsequent requests to the same runner. Sent as the X-Fal-Runner-Hint header.
webhook_url	string	No	Optional URL to receive a POST callback when the job completes, instead of (or in addition to) polling. Sent to fal.ai as the fal_webhook query parameter.
timeout_seconds	integer	No	Optional server-side execution deadline in seconds. Sent as the X-Fal-Request-Timeout header.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Subscribe to Async Inference Job

FAL_AI_SUBSCRIBE_ASYNC_JOB

Tool to submit a fal.ai inference job to the async queue and block until it completes (or a deadline is reached), returning the model’s final result. Mirrors fal-js’s subscribe() ergonomics: SUBMIT_ASYNC_JOB + QUEUE_GET_STATUS polling + GET_QUEUE_REQUEST_RESULT in one call. Use when you want async-style reliability (queue persistence, retries) but a synchronous-style return value, and the model is fast enough to finish within max_wait_seconds. For very long jobs, prefer SUBMIT_ASYNC_JOB and check status/result manually or via webhook.

Input parameters

Name	Type	Required	Description
input	object	Yes	Model-specific input payload posted as the JSON request body.
model_id	string	Yes	The model identifier in namespace/name format (e.g., fal-ai/flux/schnell). Slashes are preserved in the URL path.
priority	string ("normal" | "low")	No	Optional queue priority hint for the initial submission (X-Fal-Queue-Priority).
runner_hint	string	No	Optional session-affinity hint for the initial submission (X-Fal-Runner-Hint).
include_logs	boolean	No	If true, request runner logs along with each status poll (forwarded to fal.ai as ?logs=1).
timeout_seconds	integer	No	Optional server-side execution deadline in seconds for the initial submission (X-Fal-Request-Timeout).
max_wait_seconds	number	No	Hard deadline. If the job hasn’t transitioned to COMPLETED within this many seconds the action raises a timeout error (the underlying job is NOT cancelled). Capped at 900 to keep the action well below Composio’s serverless execution limits.
poll_interval_seconds	number	No	Seconds between status polls while the job is IN_QUEUE or IN_PROGRESS.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Upload Input File

FAL_AI_UPLOAD_FILE

Tool to upload an input media file (image, audio, or video) to fal.ai’s CDN and return a public access_url that can be passed as a model input. Many fal.ai models accept a URL for inputs like image_url, audio_url, or video_url — use this action first to host the file, then pass the access_url to RUN_MODEL_SYNC or SUBMIT_ASYNC_JOB. Internally this performs fal.ai’s two-step upload: (1) POST to rest.fal.ai/storage/upload/initiate to get a presigned upload URL, (2) PUT the bytes to that URL.

Input parameters

Name	Type	Required	Description
file	object	Yes	File to upload to fal.ai storage. The returned access_url can then be passed as a model input field (e.g., image_url, audio_url, video_url). Supported types include images (jpg, jpeg, png, gif, webp), videos (mp4, mov, webm), and audio (mp3, wav, flac).

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.