# Fal.ai

The generative media platform for developers with 600+ AI models for image, video, voice, and audio generation

- **Category:** ai models
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 8
- **Triggers:** 0
- **Slug:** `FAL_AI`
- **Version:** 20260410_00

## Tools

### Cancel Queue Request

**Slug:** `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

| Parameter | 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

| Parameter | 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 or not |

### Estimate Pricing

**Slug:** `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

| Parameter | 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

| Parameter | 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 or not |

### Get JWKS for Webhook Verification

**Slug:** `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

| Parameter | 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 or not |

### Get Models

**Slug:** `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

| Parameter | 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

| Parameter | 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 or not |

### Get Model Pricing

**Slug:** `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

| Parameter | 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

| Parameter | 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 or not |

### Get Queue Request Result

**Slug:** `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

| Parameter | 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

| Parameter | 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 or not |

### Check Queue Request Status

**Slug:** `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

| Parameter | 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

| Parameter | 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 or not |

### Stream Request Status Updates

**Slug:** `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

| Parameter | 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

| Parameter | 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 or not |

### Run Model (Sync)

**Slug:** `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

| Parameter | 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

| Parameter | 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 or not |

### Submit Async Inference Job

**Slug:** `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

| Parameter | 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

| Parameter | 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 or not |

### Subscribe to Async Inference Job

**Slug:** `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

| Parameter | 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

| Parameter | 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 or not |

### Upload Input File

**Slug:** `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

| Parameter | 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

| Parameter | 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 or not |