# Fal.ai

> Generate images, audio and video with Fal models, inspect queued jobs, and manage workflows and generated assets.

App · 25 actions. Web page: https://docs.lodol.com/docs/integrations/fal-ai

## Actions

### Analytics

Time-bucketed metrics per model endpoint, including request counts, success/error rates, and latency percentiles. prepare_duration reflects queue/prepare time before execution; duration is request execution time. Use with the Queue/Webhooks flow to monitor SLAs. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Limit (`limit`, number): Maximum number of items to return. Actual maximum depends on query type and expansion parameters. At least 1.0.
- Cursor (`cursor`, text): Pagination cursor from previous response. Encodes the page number.
- Start (`start`, date and time): Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
- End (`end`, date and time): End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time.
- Timezone (`timezone`, text): Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed.
- Timeframe (`timeframe`, text): Aggregation timeframe for timeseries data (auto-detected from date range if not specified). Auto-detection uses: minute (=183d). One of: `minute`, `hour`, `day`, `week`, `month`.
- Bound to timeframe (`bound_to_timeframe`, text): Whether to adjust start/end dates to align with timeframe boundaries and use exclusive end. Defaults to true. When true, dates are aligned to the start of the timeframe period (e.g., start of day) and end is made exclusive (e.g., start of next day). When false, uses exact dates provided. One of: `true`, `false`.
- Endpoint (`endpoint_id`, list, required): Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2
- Expand (`expand`, text): Data and metrics to include in the response. Use 'time_series' for time-bucketed data, metric names for specific metrics in time series, and 'summary' for aggregate statistics. At least one of 'time_series' or 'summary' and at least one metric are required.

**Outputs**

- `response` (object): Response containing performance analytics with pagination support

**Example output**

```json
{
  "response": {
    "has_more": false,
    "next_cursor": "example",
    "summary": [],
    "time_series": []
  }
}
```

### Browse assets

Browse and semantically search fal Assets across all media, uploads, favorites, collections, tags, and character references. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Limit (`limit`, number): Maximum number of items to return. Actual maximum depends on query type and expansion parameters. At least 1.0.
- Cursor (`cursor`, text): Pagination cursor from previous response. Encodes the page number.
- Q (`q`, text): Text query for hybrid semantic search
- Search image URL (`search_image_url`, text): fal-hosted image URL to use for semantic image search
- Search video URL (`search_video_url`, text): fal-hosted video URL to use for semantic video search
- Media type (`media_type`, list): Filter by one or more media types. One or more of: `image`, `video`, `audio`, `3d`.
- Source (`source`, list): Filter by one or more indexed sources. One or more of: `upload`, `response`.
- Section (`section`, text): Asset library section to browse. One of: `all-media`, `uploads`, `favorites`, `generated`.
- Collection ID (`collection_id`, text): Collection scope to browse
- Character identifier (`character_identifier`, list): Character identifiers to use as @mention semantic filters
- Tag ID (`tag_id`, list): Tag IDs to filter by
- Tag mode (`tag_mode`, text): Whether tag filters match any tag or all tags. One of: `any`, `all`.

**Outputs**

- `response` (object): Paginated asset browse response

**Example output**

```json
{
  "response": {
    "assets": [],
    "has_more": false,
    "next_cursor": "example",
    "scope_truncated": false,
    "total_count": 1
  }
}
```

### Browse assets in a collection

Browse assets in a collection for the authenticated user's fal Assets library. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Collection ID (`collection_id`, text, required): Collection ID
- Limit (`limit`, number): Maximum number of items to return. Actual maximum depends on query type and expansion parameters. At least 1.0.
- Cursor (`cursor`, text): Pagination cursor from previous response. Encodes the page number.
- Q (`q`, text): Text query for hybrid semantic search
- Search image URL (`search_image_url`, text): fal-hosted image URL to use for semantic image search
- Search video URL (`search_video_url`, text): fal-hosted video URL to use for semantic video search
- Media type (`media_type`, list): Filter by one or more media types. One or more of: `image`, `video`, `audio`, `3d`.
- Source (`source`, list): Filter by one or more indexed sources. One or more of: `upload`, `response`.
- Section (`section`, text): Asset library section to browse. One of: `all-media`, `uploads`, `favorites`, `generated`.
- Character identifier (`character_identifier`, list): Character identifiers to use as @mention semantic filters
- Tag ID (`tag_id`, list): Tag IDs to filter by
- Tag mode (`tag_mode`, text): Whether tag filters match any tag or all tags. One of: `any`, `all`.

**Outputs**

- `response` (object): Paginated asset browse response

**Example output**

```json
{
  "response": {
    "assets": [],
    "has_more": false,
    "next_cursor": "example",
    "scope_truncated": false,
    "total_count": 1
  }
}
```

### Cancel a request

Cancel a queue request. If the request is in the queue, fal removes it. If the request is in progress, fal sends a cancellation signal to the runner. The model app decides how to stop the work. See Handle cancellations.

**Inputs**

- Model (`model_id`, text, required): Model endpoint ID from its Fal page, for example fal-ai/flux/schnell.
- Request ID (`request_id`, text, required): The request ID that the submit response returned.

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "status": "OK"
  }
}
```

### Create a workflow

Create a new workflow owned by the authenticated user.

**Inputs**

- Name (`name`, text, required): Unique workflow name/slug within the user's namespace
- Title (`title`, text, required): Human-readable workflow title
- Contents (`contents`, object, required): The workflow definition/configuration object
- Is public (`is_public`, true/false): Whether the workflow is publicly visible

**Outputs**

- `response` (object): Response containing a single workflow's details

**Example output**

```json
{
  "response": {
    "workflow": {
      "contents": {},
      "created_at": "example",
      "is_public": false,
      "name": "example",
      "title": "example",
      "user_nickname": "example"
    }
  }
}
```

### Create asset collection

Create asset collection for the authenticated user's fal Assets library.

**Inputs**

- Name (`name`, text, required): Collection display name
- Description (`description`, text): Optional collection description
- Icon (`icon`, text): Optional collection icon
- Color (`color`, text): Optional collection color
- Cover image URL (`cover_image_url`, text): Optional fal-hosted cover image URL for the collection
- Parent collection ID (`parent_collection_id`, text): Optional parent collection ID to nest this collection under (manual collections only). Omit or null to create a top-level collection.
- Filters (`filters`, text): Assets filter DSL

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "collection": {
      "asset_count": 1,
      "character_identifier": "example",
      "color": "example",
      "cover_image_url": "example",
      "created_at": "example",
      "description": "example",
      "filters": {},
      "icon": "example",
      "id": "example",
      "is_favorited": false,
      "name": "example",
      "parent_collection_id": "example",
      "type": "manual",
      "updated_at": "example"
    }
  }
}
```

### Create asset tag

Create asset tag for the authenticated user's fal Assets library.

**Inputs**

- Name (`name`, text, required): Tag name

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "tag": {
      "created_at": "example",
      "id": "example",
      "name": "example"
    }
  }
}
```

### Delete asset collection

Delete asset collection for the authenticated user's fal Assets library.

**Inputs**

- Collection ID (`collection_id`, text, required): Collection ID

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {}
}
```

### Delete asset tag

Delete asset tag for the authenticated user's fal Assets library.

**Inputs**

- Tag ID (`tag_id`, text, required): Tag ID

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {}
}
```

### Estimate cost

Computes cost estimates using one of two methods:

**Inputs**

- Estimate type (`estimate_type`, text, required): Estimate type: historical API pricing based on past usage patterns. One of: `historical_api_price` (historical api price), `unit_price` (unit price).
- Endpoints (`endpoints`, object, required): Map of endpoint IDs to call quantities

**Outputs**

- `response` (object): Cost estimation response with total cost

**Example output**

```json
{
  "response": {
    "currency": "example",
    "estimate_type": "historical_api_price",
    "total_cost": 0
  }
}
```

### Get asset

Get an asset from the authenticated user's fal Assets library by asset ID; a vector ID is also accepted. Returns 404 when the asset has no live catalog record, including one whose deletion has not yet propagated to the search index.

**Inputs**

- Asset ID (`asset_id`, text, required): Asset ID. A vector ID is also accepted

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "asset": {
      "asset_id": "example",
      "collection_ids": [],
      "content_type": "example",
      "created_at": "example",
      "endpoint": "example",
      "height": 1,
      "is_favorited": false,
      "prompt": "example",
      "request_id": "example",
      "similarity": 1,
      "source": "example",
      "tags": [],
      "title": "example",
      "type": "image",
      "url": "example",
      "vector_id": "example",
      "width": 1
    }
  }
}
```

### Get asset collection

Get asset collection for the authenticated user's fal Assets library.

**Inputs**

- Collection ID (`collection_id`, text, required): Collection ID

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "collection": {
      "asset_count": 1,
      "character_identifier": "example",
      "color": "example",
      "cover_image_url": "example",
      "created_at": "example",
      "description": "example",
      "filters": {},
      "icon": "example",
      "id": "example",
      "is_favorited": false,
      "name": "example",
      "parent_collection_id": "example",
      "type": "manual",
      "updated_at": "example"
    }
  }
}
```

### Get request result

Get the result of a completed request. The response has the status code, headers, and body that the model returned. If the model returned an error, this operation returns the same error.

**Inputs**

- Model (`model_id`, text, required): Model endpoint ID from its Fal page, for example fal-ai/flux/schnell.
- Request ID (`request_id`, text, required): The request ID that the submit response returned.

**Outputs**

- `response` (object): The model output. Each model has its own output schema.

**Example output**

```json
{
  "response": {}
}
```

### Get request status

Get the state of a queue request. Poll this operation until status is COMPLETED, then get the result. To receive updates without polling, use the status stream.

**Inputs**

- Model (`model_id`, text, required): Model endpoint ID from its Fal page, for example fal-ai/flux/schnell.
- Request ID (`request_id`, text, required): The request ID that the submit response returned.
- Logs (`logs`, text): Set to 1 to include runner logs in the response. Logs are not available for all models. One of: `1`, `0`.

**Outputs**

- `response` (object): The state of a queue request.

**Example output**

```json
{
  "response": {
    "cancel_url": "example",
    "error": "example",
    "error_type": "example",
    "logs": [],
    "metrics": {
      "inference_time": 1
    },
    "queue_position": 1,
    "request_id": "example",
    "response_url": "example",
    "status": "IN_QUEUE",
    "status_url": "example"
  }
}
```

### Get workflow details

Get detailed information about a specific workflow, including its full contents/definition.

**Inputs**

- Username (`username`, text, required): The username of the workflow owner
- Workflow name (`workflow_name`, text, required): The workflow name/slug

**Outputs**

- `response` (object): Response containing a single workflow's details

**Example output**

```json
{
  "response": {
    "workflow": {
      "contents": {},
      "created_at": "example",
      "is_public": false,
      "name": "example",
      "title": "example",
      "user_nickname": "example"
    }
  }
}
```

### List asset collections

List asset collections for the authenticated user's fal Assets library. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Limit (`limit`, number): Maximum number of collections to return. From 1.0 to 100.0.
- Offset (`offset`, number): Number of collections to skip. At least 0.0.

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "collections": []
  }
}
```

### List asset tags

List asset tags for the authenticated user's fal Assets library. Gets one page; to see more, run it again with the next page it gives.

**Inputs**: None.

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "tags": []
  }
}
```

### List requests by endpoint(s)

List requests for one or more endpoints (same endpoint_id style as usage/explore: comma-separated or repeated query params, up to 50 IDs). Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Limit (`limit`, number): Number of items to return per page (max 100). From 1.0 to 100.0.
- Cursor (`cursor`, text): Pagination cursor encoding the page number
- Endpoint (`endpoint_id`, list, required): Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2
- Start (`start`, date and time): Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
- End (`end`, date and time): End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time.
- Status (`status`, text): Filter by request status. One of: `success`, `error`, `user_error` (user error).
- Request ID (`request_id`, text): Filter by specific request ID
- Expand (`expand`, text): Fields to expand in the response. Use payloads to include input and output payloads.
- Sort by (`sort_by`, text): Sort results by end time or duration. One of: `ended_at` (ended at), `duration`.

**Outputs**

- `response` (object): Paginated list of requests for the specified endpoint

**Example output**

```json
{
  "response": {
    "has_more": false,
    "items": [],
    "next_cursor": "example"
  }
}
```

### List user workflows

List workflows for the authenticated user with optional search and filtering. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Limit (`limit`, number): Maximum number of items to return. Actual maximum depends on query type and expansion parameters. At least 1.0.
- Cursor (`cursor`, text): Pagination cursor from previous response. Encodes the page number.
- Search (`search`, text): Search by workflow name or title
- Used endpoint IDS (`used_endpoint_ids`, list): Filter by model endpoint IDs used in the workflow. Can be a single value or comma-separated values.

**Outputs**

- `response` (object): Response containing workflow data with pagination support

**Example output**

```json
{
  "response": {
    "has_more": false,
    "next_cursor": "example",
    "total": 1,
    "workflows": []
  }
}
```

### Model search

Unified endpoint for discovering model endpoints. Supports three usage modes: Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Limit (`limit`, number): Maximum number of items to return. Actual maximum depends on query type and expansion parameters. At least 1.0.
- Cursor (`cursor`, text): Pagination cursor from previous response. Encodes the page number.
- Endpoint (`endpoint_id`, list): Endpoint ID(s) to retrieve (e.g., 'fal-ai/flux/dev'). Can be a single value or multiple values (1-50 models). When combined with search params, narrows results to these IDs. Use array syntax: ?endpoint_id=model1&endpoint_id=model2
- Q (`q`, text): Free-text search query to filter models by name, description, or category
- Category (`category`, text): Filter by category (e.g., 'text-to-image', 'image-to-video', 'training')
- Status (`status`, text): Filter models by status - omit to include all statuses. One of: `active`, `deprecated`.
- Sort (`sort`, text): List/search ordering: relevant uses Explore's shared Trending browse order or keyword relevance; recent sorts by publication date (creation date when the publication date is missing). Defaults to relevant. Ignored in endpoint_id find mode, which preserves input order. Keep sort, filters and limit unchanged when following a cursor. One of: `relevant`, `recent`.
- Expand (`expand`, list): Fields to expand in the response. Supported values: 'openapi-3.0' (includes full OpenAPI 3.0 schema in 'openapi' field), 'enterprise_status' (includes enterprise readiness status). One or more of: `openapi-3.0`, `enterprise_status` (enterprise status).

**Outputs**

- `response` (object): Response containing model data with pagination support

**Example output**

```json
{
  "response": {
    "has_more": false,
    "models": [],
    "next_cursor": "example",
    "ordering": {
      "sort": "relevant"
    }
  }
}
```

### Pricing

Get unit pricing for requested endpoint IDs. Most models use output-based pricing (e.g., per image/video with proportional adjustments for resolution/length). Some models use GPU-based pricing depending on architecture. Values are expressed per model's billing unit in a given currency.

**Inputs**

- Endpoint (`endpoint_id`, list, required): Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2

**Outputs**

- `response` (object): Response containing pricing information for requested endpoints

**Example output**

```json
{
  "response": {
    "has_more": false,
    "next_cursor": "example",
    "prices": []
  }
}
```

### Submit a request

Add a model request to the queue. The response contains the request ID and the URLs for status, result, and cancellation. The queue keeps the request until a runner is available. The queue has no size limit unless you send fal_max_queue_length.

**Inputs**

- Model (`model_id`, text, required): Model endpoint ID from its Fal page, for example fal-ai/flux/schnell.
- Fal webhook (`fal_webhook`, text): An http or https URL. fal sends a POST request to this URL when the request completes. See [Webhooks](/documentation/model-apis/inference/webhooks).
- Fal max queue length (`fal_max_queue_length`, number): The maximum number of queued requests. If the queue for this endpoint already has this number of requests, the API rejects the request with 429.
- Input (`input`, object, required): Inputs required by the chosen model. Copy the input example from the model page on fal.ai.

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "cancel_url": "example",
    "error": "example",
    "error_type": "example",
    "logs": [],
    "metrics": {
      "inference_time": 1
    },
    "queue_position": 1,
    "request_id": "example",
    "response_url": "example",
    "status": "IN_QUEUE",
    "status_url": "example"
  }
}
```

### Update asset collection

Update asset collection for the authenticated user's fal Assets library.

**Inputs**

- Collection ID (`collection_id`, text, required): Collection ID
- Name (`name`, text): Collection display name
- Description (`description`, text): Optional collection description
- Icon (`icon`, text): Optional collection icon
- Color (`color`, text): Optional collection color
- Cover image URL (`cover_image_url`, text): Optional fal-hosted cover image URL for the collection
- Filters (`filters`, text): Assets filter DSL

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "collection": {
      "asset_count": 1,
      "character_identifier": "example",
      "color": "example",
      "cover_image_url": "example",
      "created_at": "example",
      "description": "example",
      "filters": {},
      "icon": "example",
      "id": "example",
      "is_favorited": false,
      "name": "example",
      "parent_collection_id": "example",
      "type": "manual",
      "updated_at": "example"
    }
  }
}
```

### Update asset tag

Update asset tag for the authenticated user's fal Assets library.

**Inputs**

- Tag ID (`tag_id`, text, required): Tag ID
- Name (`name`, text): Tag name

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "tag": {
      "created_at": "example",
      "id": "example",
      "name": "example"
    }
  }
}
```

### Usage

Get paginated usage records for your workspace with filters for endpoint, user, date range, and auth method. Each item includes the billed unit quantity, the pre-discount unit price and cost_subtotal, any percentage discount applied, and the final cost_total (cost_subtotal minus cost_discount). Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Limit (`limit`, number): Maximum number of items to return. Actual maximum depends on query type and expansion parameters. At least 1.0.
- Cursor (`cursor`, text): Pagination cursor from previous response. Encodes the page number.
- Start (`start`, date and time): Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
- End (`end`, date and time): End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time.
- Timezone (`timezone`, text): Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed.
- Timeframe (`timeframe`, text): Aggregation timeframe for timeseries data (auto-detected from date range if not specified). Auto-detection uses: minute (=183d). One of: `minute`, `hour`, `day`, `week`, `month`.
- Bound to timeframe (`bound_to_timeframe`, text): Whether to adjust start/end dates to align with timeframe boundaries and use exclusive end. Defaults to true. When true, dates are aligned to the start of the timeframe period (e.g., start of day) and end is made exclusive (e.g., start of next day). When false, uses exact dates provided. One of: `true`, `false`.
- Source (`source`, text): Data source. 'estimate' is the default usage estimate. 'tagged-estimate' reads the tagged aggregate instead, populating each row's 'tags' and enabling the 'tag' filter; it requires tagged reporting to be enabled for the account, and recent usage is delayed relative to 'estimate'. One of: `estimate`, `tagged-estimate`.
- Endpoint (`endpoint_id`, list): Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2
- API key ID (`api_key_id`, text): Filter by specific API key ID(s). Accepts 1-50 key IDs. Supports comma-separated values: ?api_key_id=key1,key2 or array syntax: ?api_key_id=key1&api_key_id=key2
- Login username (`login_username`, text): Filter by team member login username(s) (nickname). Accepts 1-50 usernames. Supports comma-separated values: ?login_username=alice,bob or array syntax: ?login_username=alice&login_username=bob
- Tag (`tag`, text): Filter by X-Fal-Tags 'key=value' pairs. Accepts 1-10 filters: different keys are AND-combined (?tag=env=prod&tag=team=design), and repeating a key matches any of its values. Use the value '(untagged)' to match requests that did not set the key.
- Expand (`expand`, text): Data to include in the response. Use 'time_series' for time-bucketed data, 'summary' for aggregate statistics, 'auth_method' to include a formatted authentication method label, and 'auth_method_structured' to include a machine-readable auth method object (detail, api_key_id, login_username). At least one of 'time_series' or 'summary' is required.

**Outputs**

- `response` (object): Response containing usage data with pagination support

**Example output**

```json
{
  "response": {
    "has_more": false,
    "next_cursor": "example",
    "summary": [],
    "time_series": []
  }
}
```
