> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modulex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# fal.ai Integration for AI Agents & Workflows

> Queue-based AI model inference via the fal.ai platform

{/* Self-hosted logo — build-time vendored from modulex.json / Iconify (see scripts/lib/logo.js). */}

<img src="https://mintcdn.com/modulexaillc/zKB2qsP6Q61VNLfB/logos/fal-ai.svg?fit=max&auto=format&n=zKB2qsP6Q61VNLfB&q=85&s=24fd4e07b2e6db4e17f6b5280e7db9fe" alt="fal.ai logo" width="72" height="72" data-path="logos/fal-ai.svg" />

## Overview

Add **fal.ai** to any ModuleX agent or workflow. Queue-based AI model inference via the fal.ai platform API (`queue.fal.run/fal-ai`). Submit requests to run generative AI models asynchronously, monitor their status, retrieve results, and cancel pending tasks.

<Info>
  **Categories**: AI & Machine Learning · Generative AI · **Auth**: API Key · **Actions**: 4
</Info>

## Authentication

### API Key Authentication

Authenticate using your fal.ai API key

<Steps>
  <Step title="Step 1">
    Go to [https://fal.ai/dashboard/keys](https://fal.ai/dashboard/keys) and sign in
  </Step>

  <Step title="Step 2">
    Create a new API key or copy your existing one
  </Step>

  <Step title="Step 3">
    Paste the API key below
  </Step>
</Steps>

#### Required Credentials

| Field          | Description                                                                             | Required | Format                                                                  |
| -------------- | --------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------- |
| fal.ai API Key | Your fal.ai API key from [https://fal.ai/dashboard/keys](https://fal.ai/dashboard/keys) | Yes      | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |

## Available Actions

<AccordionGroup>
  <Accordion title="add_request_to_queue — Adds a request to the queue for asynchronous processing, including specifying a webhook URL for receiving updates">
    ### Parameters

    <ResponseField name="app_id" type="string" required>
      The unique identifier for the fal.ai app/model (e.g. 'lora', 'fast-sdxl')
    </ResponseField>

    <ResponseField name="data" type="object" required>
      Input data for the model. Fields depend on the specific app/model being called
    </ResponseField>

    <ResponseField name="webhook_url" type="string">
      Optional URL to receive webhook updates about the request status
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "request_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Request Id"
        },
        "response_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Response Url"
        },
        "status_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Status Url"
        },
        "cancel_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Cancel Url"
        }
      },
      "required": [
        "success"
      ],
      "title": "AddRequestToQueueOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="cancel_request — Cancels a request in the queue to stop a long-running task that is no longer needed">
    ### Parameters

    <ResponseField name="app_id" type="string" required>
      The unique identifier for the fal.ai app/model
    </ResponseField>

    <ResponseField name="request_id" type="string" required>
      The unique identifier for the request to cancel
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        }
      },
      "required": [
        "success"
      ],
      "title": "CancelRequestOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="get_request_response — Gets the response of a completed request in the queue to retrieve results of an asynchronous task">
    ### Parameters

    <ResponseField name="app_id" type="string" required>
      The unique identifier for the fal.ai app/model
    </ResponseField>

    <ResponseField name="request_id" type="string" required>
      The unique identifier for the request
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "data": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Data"
        }
      },
      "required": [
        "success"
      ],
      "title": "GetRequestResponseOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="get_request_status — Gets the status of a request in the queue to monitor the progress of an asynchronous task">
    ### Parameters

    <ResponseField name="app_id" type="string" required>
      The unique identifier for the fal.ai app/model
    </ResponseField>

    <ResponseField name="request_id" type="string" required>
      The unique identifier for the request
    </ResponseField>

    <ResponseField name="logs" type="boolean">
      Whether to include logs in the status response
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "LogEntry": {
          "additionalProperties": false,
          "description": "A log entry from a queued request's status.",
          "properties": {
            "message": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Message"
            },
            "level": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Level"
            },
            "timestamp": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Timestamp"
            }
          },
          "title": "LogEntry",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Status"
        },
        "queue_position": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Queue Position"
        },
        "logs": {
          "items": {
            "$ref": "#/$defs/LogEntry"
          },
          "title": "Logs",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "GetRequestStatusOutput",
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## Limits & Quotas

* Rate limits depend on your fal.ai plan tier (free tier has limited concurrent requests).
* Requests are queued; queue position is returned in status responses.
* Error model: non-2xx responses and timeouts are caught and returned as `success=False` + `error` rather than raising.

## Related integrations

<CardGroup cols={3}>
  <Card title="Amazon Alexa" href="/integrations/tools/amazon-alexa" />

  <Card title="Browser Use" href="/integrations/tools/browser-use" />

  <Card title="ElevenLabs" href="/integrations/tools/elevenlabs" />
</CardGroup>

## Links

* [fal.ai](https://fal.ai)