Fal.ai

App · 25 actions

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

Actions

ActionWhat it does
AnalyticsTime-bucketed metrics per model endpoint, including request counts, success/error rates, and latency percentiles.
Browse assetsBrowse and semantically search fal Assets across all media, uploads, favorites, collections, tags, and character references.
Browse assets in a collectionBrowse assets in a collection for the authenticated user's fal Assets library.
Cancel a requestCancel a queue request.
Create a workflowCreate a new workflow owned by the authenticated user.
Create asset collectionCreate asset collection for the authenticated user's fal Assets library.
Create asset tagCreate asset tag for the authenticated user's fal Assets library.
Delete asset collectionDelete asset collection for the authenticated user's fal Assets library.
Delete asset tagDelete asset tag for the authenticated user's fal Assets library.
Estimate costComputes cost estimates using one of two methods:
Get assetGet an asset from the authenticated user's fal Assets library by asset ID; a vector ID is also accepted.
Get asset collectionGet asset collection for the authenticated user's fal Assets library.
Get request resultGet the result of a completed request.
Get request statusGet the state of a queue request.
Get workflow detailsGet detailed information about a specific workflow, including its full contents/definition.
List asset collectionsList asset collections for the authenticated user's fal Assets library.
List asset tagsList asset tags for the authenticated user's fal Assets library.
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).
List user workflowsList workflows for the authenticated user with optional search and filtering.
Model searchUnified endpoint for discovering model endpoints.
PricingGet unit pricing for requested endpoint IDs.
Submit a requestAdd a model request to the queue.
Update asset collectionUpdate asset collection for the authenticated user's fal Assets library.
Update asset tagUpdate asset tag for the authenticated user's fal Assets library.
UsageGet paginated usage records for your workspace with filters for endpoint, user, date range, and auth method.

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

Limitlimitnumber
Maximum number of items to return. Actual maximum depends on query type and expansion parameters.At least 1.0.
Cursorcursortext
Pagination cursor from previous response. Encodes the page number.
Startstartdate and time
Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
Endenddate 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.
Timezonetimezonetext
Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed.
Timeframetimeframetext
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 timeframebound_to_timeframetext
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.
Endpointendpoint_idlistRequired
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
Expandexpandtext
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

responseobject
Response containing performance analytics with pagination support
Example output
{
  "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

Limitlimitnumber
Maximum number of items to return. Actual maximum depends on query type and expansion parameters.At least 1.0.
Cursorcursortext
Pagination cursor from previous response. Encodes the page number.
Qqtext
Text query for hybrid semantic search
Search image URLsearch_image_urltext
fal-hosted image URL to use for semantic image search
Search video URLsearch_video_urltext
fal-hosted video URL to use for semantic video search
Media typemedia_typelist
Filter by one or more media typesOne or more of: image, video, audio, 3d.
Sourcesourcelist
Filter by one or more indexed sourcesOne or more of: upload, response.
Sectionsectiontext
Asset library section to browseOne of: all-media, uploads, favorites, generated.
Collection IDcollection_idtext
Collection scope to browse
Character identifiercharacter_identifierlist
Character identifiers to use as @mention semantic filters
Tag IDtag_idlist
Tag IDs to filter by
Tag modetag_modetext
Whether tag filters match any tag or all tagsOne of: any, all.

Outputs

responseobject
Paginated asset browse response
Example output
{
  "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 IDcollection_idtextRequired
Collection ID
Limitlimitnumber
Maximum number of items to return. Actual maximum depends on query type and expansion parameters.At least 1.0.
Cursorcursortext
Pagination cursor from previous response. Encodes the page number.
Qqtext
Text query for hybrid semantic search
Search image URLsearch_image_urltext
fal-hosted image URL to use for semantic image search
Search video URLsearch_video_urltext
fal-hosted video URL to use for semantic video search
Media typemedia_typelist
Filter by one or more media typesOne or more of: image, video, audio, 3d.
Sourcesourcelist
Filter by one or more indexed sourcesOne or more of: upload, response.
Sectionsectiontext
Asset library section to browseOne of: all-media, uploads, favorites, generated.
Character identifiercharacter_identifierlist
Character identifiers to use as @mention semantic filters
Tag IDtag_idlist
Tag IDs to filter by
Tag modetag_modetext
Whether tag filters match any tag or all tagsOne of: any, all.

Outputs

responseobject
Paginated asset browse response
Example output
{
  "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

Modelmodel_idtextRequired
Model endpoint ID from its Fal page, for example fal-ai/flux/schnell.
Request IDrequest_idtextRequired
The request ID that the submit response returned.

Outputs

responseobject
Response.
Example output
{
  "response": {
    "status": "OK"
  }
}

Create a workflow

Create a new workflow owned by the authenticated user.

Inputs

NamenametextRequired
Unique workflow name/slug within the user's namespace
TitletitletextRequired
Human-readable workflow title
ContentscontentsobjectRequired
The workflow definition/configuration object
Is publicis_publictrue/false
Whether the workflow is publicly visible

Outputs

responseobject
Response containing a single workflow's details
Example output
{
  "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

NamenametextRequired
Collection display name
Descriptiondescriptiontext
Optional collection description
Iconicontext
Optional collection icon
Colorcolortext
Optional collection color
Cover image URLcover_image_urltext
Optional fal-hosted cover image URL for the collection
Parent collection IDparent_collection_idtext
Optional parent collection ID to nest this collection under (manual collections only). Omit or null to create a top-level collection.
Filtersfilterstext
Assets filter DSL

Outputs

responseobject
Response.
Example output
{
  "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

NamenametextRequired
Tag name

Outputs

responseobject
Response.
Example output
{
  "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 IDcollection_idtextRequired
Collection ID

Outputs

responseobject
Response.
Example output
{
  "response": {}
}

Delete asset tag

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

Inputs

Tag IDtag_idtextRequired
Tag ID

Outputs

responseobject
Response.
Example output
{
  "response": {}
}

Estimate cost

Computes cost estimates using one of two methods:

Inputs

Estimate typeestimate_typetextRequired
Estimate type: historical API pricing based on past usage patternsOne of: historical_api_price (historical api price), unit_price (unit price).
EndpointsendpointsobjectRequired
Map of endpoint IDs to call quantities

Outputs

responseobject
Cost estimation response with total cost
Example output
{
  "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 IDasset_idtextRequired
Asset ID. A vector ID is also accepted

Outputs

responseobject
Response.
Example output
{
  "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 IDcollection_idtextRequired
Collection ID

Outputs

responseobject
Response.
Example output
{
  "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

Modelmodel_idtextRequired
Model endpoint ID from its Fal page, for example fal-ai/flux/schnell.
Request IDrequest_idtextRequired
The request ID that the submit response returned.

Outputs

responseobject
The model output. Each model has its own output schema.
Example output
{
  "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

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

Outputs

responseobject
The state of a queue request.
Example output
{
  "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

UsernameusernametextRequired
The username of the workflow owner
Workflow nameworkflow_nametextRequired
The workflow name/slug

Outputs

responseobject
Response containing a single workflow's details
Example output
{
  "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

Limitlimitnumber
Maximum number of collections to returnFrom 1.0 to 100.0.
Offsetoffsetnumber
Number of collections to skipAt least 0.0.

Outputs

responseobject
Response.
Example output
{
  "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

responseobject
Response.
Example output
{
  "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

Limitlimitnumber
Number of items to return per page (max 100)From 1.0 to 100.0.
Cursorcursortext
Pagination cursor encoding the page number
Endpointendpoint_idlistRequired
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
Startstartdate and time
Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
Endenddate 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.
Statusstatustext
Filter by request statusOne of: success, error, user_error (user error).
Request IDrequest_idtext
Filter by specific request ID
Expandexpandtext
Fields to expand in the response. Use payloads to include input and output payloads.
Sort bysort_bytext
Sort results by end time or durationOne of: ended_at (ended at), duration.

Outputs

responseobject
Paginated list of requests for the specified endpoint
Example output
{
  "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

Limitlimitnumber
Maximum number of items to return. Actual maximum depends on query type and expansion parameters.At least 1.0.
Cursorcursortext
Pagination cursor from previous response. Encodes the page number.
Searchsearchtext
Search by workflow name or title
Used endpoint IDSused_endpoint_idslist
Filter by model endpoint IDs used in the workflow. Can be a single value or comma-separated values.

Outputs

responseobject
Response containing workflow data with pagination support
Example output
{
  "response": {
    "has_more": false,
    "next_cursor": "example",
    "total": 1,
    "workflows": []
  }
}

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

Limitlimitnumber
Maximum number of items to return. Actual maximum depends on query type and expansion parameters.At least 1.0.
Cursorcursortext
Pagination cursor from previous response. Encodes the page number.
Endpointendpoint_idlist
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
Qqtext
Free-text search query to filter models by name, description, or category
Categorycategorytext
Filter by category (e.g., 'text-to-image', 'image-to-video', 'training')
Statusstatustext
Filter models by status - omit to include all statusesOne of: active, deprecated.
Sortsorttext
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.
Expandexpandlist
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

responseobject
Response containing model data with pagination support
Example output
{
  "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

Endpointendpoint_idlistRequired
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

responseobject
Response containing pricing information for requested endpoints
Example output
{
  "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

Modelmodel_idtextRequired
Model endpoint ID from its Fal page, for example fal-ai/flux/schnell.
Fal webhookfal_webhooktext
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 lengthfal_max_queue_lengthnumber
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.
InputinputobjectRequired
Inputs required by the chosen model. Copy the input example from the model page on fal.ai.

Outputs

responseobject
Response.
Example output
{
  "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 IDcollection_idtextRequired
Collection ID
Namenametext
Collection display name
Descriptiondescriptiontext
Optional collection description
Iconicontext
Optional collection icon
Colorcolortext
Optional collection color
Cover image URLcover_image_urltext
Optional fal-hosted cover image URL for the collection
Filtersfilterstext
Assets filter DSL

Outputs

responseobject
Response.
Example output
{
  "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 IDtag_idtextRequired
Tag ID
Namenametext
Tag name

Outputs

responseobject
Response.
Example output
{
  "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

Limitlimitnumber
Maximum number of items to return. Actual maximum depends on query type and expansion parameters.At least 1.0.
Cursorcursortext
Pagination cursor from previous response. Encodes the page number.
Startstartdate and time
Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
Endenddate 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.
Timezonetimezonetext
Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed.
Timeframetimeframetext
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 timeframebound_to_timeframetext
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.
Sourcesourcetext
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.
Endpointendpoint_idlist
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 IDapi_key_idtext
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 usernamelogin_usernametext
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
Tagtagtext
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.
Expandexpandtext
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

responseobject
Response containing usage data with pagination support
Example output
{
  "response": {
    "has_more": false,
    "next_cursor": "example",
    "summary": [],
    "time_series": []
  }
}

On this page