Fal.ai
App · 25 actions
Generate images, audio and video with Fal models, inspect queued jobs, and manage workflows and generated assets.
Actions
| Action | What it does |
|---|---|
| Analytics | Time-bucketed metrics per model endpoint, including request counts, success/error rates, and latency percentiles. |
| Browse assets | Browse and semantically search fal Assets across all media, uploads, favorites, collections, tags, and character references. |
| Browse assets in a collection | Browse assets in a collection for the authenticated user's fal Assets library. |
| Cancel a request | Cancel a queue request. |
| Create a workflow | Create a new workflow owned by the authenticated user. |
| Create asset collection | Create asset collection for the authenticated user's fal Assets library. |
| Create asset tag | Create asset tag for the authenticated user's fal Assets library. |
| Delete asset collection | Delete asset collection for the authenticated user's fal Assets library. |
| Delete asset tag | Delete asset tag for the authenticated user's fal Assets library. |
| Estimate cost | Computes cost estimates using one of two methods: |
| Get asset | Get an asset from the authenticated user's fal Assets library by asset ID; a vector ID is also accepted. |
| Get asset collection | Get asset collection for the authenticated user's fal Assets library. |
| Get request result | Get the result of a completed request. |
| Get request status | Get the state of a queue request. |
| Get workflow details | Get detailed information about a specific workflow, including its full contents/definition. |
| List asset collections | List asset collections for the authenticated user's fal Assets library. |
| List asset tags | List 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 workflows | List workflows for the authenticated user with optional search and filtering. |
| Model search | Unified endpoint for discovering model endpoints. |
| Pricing | Get unit pricing for requested endpoint IDs. |
| Submit a request | Add a model request to the queue. |
| Update asset collection | Update asset collection for the authenticated user's fal Assets library. |
| Update asset tag | Update asset tag for the authenticated user's fal Assets library. |
| Usage | Get 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
- Limit
limitnumber - Maximum number of items to return. Actual maximum depends on query type and expansion parameters.At least 1.0.
- Cursor
cursortext - Pagination cursor from previous response. Encodes the page number.
- Start
startdate and time - Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
- End
enddate 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
timezonetext - Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed.
- Timeframe
timeframetext - 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_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. - Endpoint
endpoint_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
- Expand
expandtext - 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
- Limit
limitnumber - Maximum number of items to return. Actual maximum depends on query type and expansion parameters.At least 1.0.
- Cursor
cursortext - Pagination cursor from previous response. Encodes the page number.
- Q
qtext - Text query for hybrid semantic search
- Search image URL
search_image_urltext - fal-hosted image URL to use for semantic image search
- Search video URL
search_video_urltext - fal-hosted video URL to use for semantic video search
- Media type
media_typelist - Filter by one or more media typesOne or more of:
image,video,audio,3d. - Source
sourcelist - Filter by one or more indexed sourcesOne or more of:
upload,response. - Section
sectiontext - Asset library section to browseOne of:
all-media,uploads,favorites,generated. - Collection ID
collection_idtext - Collection scope to browse
- Character identifier
character_identifierlist - Character identifiers to use as @mention semantic filters
- Tag ID
tag_idlist - Tag IDs to filter by
- Tag mode
tag_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 ID
collection_idtextRequired - Collection ID
- Limit
limitnumber - Maximum number of items to return. Actual maximum depends on query type and expansion parameters.At least 1.0.
- Cursor
cursortext - Pagination cursor from previous response. Encodes the page number.
- Q
qtext - Text query for hybrid semantic search
- Search image URL
search_image_urltext - fal-hosted image URL to use for semantic image search
- Search video URL
search_video_urltext - fal-hosted video URL to use for semantic video search
- Media type
media_typelist - Filter by one or more media typesOne or more of:
image,video,audio,3d. - Source
sourcelist - Filter by one or more indexed sourcesOne or more of:
upload,response. - Section
sectiontext - Asset library section to browseOne of:
all-media,uploads,favorites,generated. - Character identifier
character_identifierlist - Character identifiers to use as @mention semantic filters
- Tag ID
tag_idlist - Tag IDs to filter by
- Tag mode
tag_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
- Model
model_idtextRequired - Model endpoint ID from its Fal page, for example fal-ai/flux/schnell.
- Request ID
request_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
- Name
nametextRequired - Unique workflow name/slug within the user's namespace
- Title
titletextRequired - Human-readable workflow title
- Contents
contentsobjectRequired - The workflow definition/configuration object
- Is public
is_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
- Name
nametextRequired - Collection display name
- Description
descriptiontext - Optional collection description
- Icon
icontext - Optional collection icon
- Color
colortext - Optional collection color
- Cover image URL
cover_image_urltext - Optional fal-hosted cover image URL for the collection
- Parent collection ID
parent_collection_idtext - Optional parent collection ID to nest this collection under (manual collections only). Omit or null to create a top-level collection.
- Filters
filterstext - 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
- Name
nametextRequired - 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 ID
collection_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 ID
tag_idtextRequired - Tag ID
Outputs
responseobject- Response.
Example output
{
"response": {}
}Estimate cost
Computes cost estimates using one of two methods:
Inputs
- Estimate type
estimate_typetextRequired - Estimate type: historical API pricing based on past usage patternsOne of:
historical_api_price(historical api price),unit_price(unit price). - Endpoints
endpointsobjectRequired - 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 ID
asset_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 ID
collection_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
- Model
model_idtextRequired - Model endpoint ID from its Fal page, for example fal-ai/flux/schnell.
- Request ID
request_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
- Model
model_idtextRequired - Model endpoint ID from its Fal page, for example fal-ai/flux/schnell.
- Request ID
request_idtextRequired - The request ID that the submit response returned.
- Logs
logstext - 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
- Username
usernametextRequired - The username of the workflow owner
- Workflow name
workflow_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
- Limit
limitnumber - Maximum number of collections to returnFrom 1.0 to 100.0.
- Offset
offsetnumber - 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
- Limit
limitnumber - Number of items to return per page (max 100)From 1.0 to 100.0.
- Cursor
cursortext - Pagination cursor encoding the page number
- Endpoint
endpoint_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
- Start
startdate and time - Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
- End
enddate 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
statustext - Filter by request statusOne of:
success,error,user_error(user error). - Request ID
request_idtext - Filter by specific request ID
- Expand
expandtext - Fields to expand in the response. Use payloads to include input and output payloads.
- Sort by
sort_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
- Limit
limitnumber - Maximum number of items to return. Actual maximum depends on query type and expansion parameters.At least 1.0.
- Cursor
cursortext - Pagination cursor from previous response. Encodes the page number.
- Search
searchtext - Search by workflow name or title
- Used endpoint IDS
used_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": []
}
}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
limitnumber - Maximum number of items to return. Actual maximum depends on query type and expansion parameters.At least 1.0.
- Cursor
cursortext - Pagination cursor from previous response. Encodes the page number.
- Endpoint
endpoint_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
- Q
qtext - Free-text search query to filter models by name, description, or category
- Category
categorytext - Filter by category (e.g., 'text-to-image', 'image-to-video', 'training')
- Status
statustext - Filter models by status - omit to include all statusesOne of:
active,deprecated. - Sort
sorttext - 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
expandlist - 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
- Endpoint
endpoint_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
- Model
model_idtextRequired - Model endpoint ID from its Fal page, for example fal-ai/flux/schnell.
- Fal webhook
fal_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 length
fal_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.
- Input
inputobjectRequired - 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 ID
collection_idtextRequired - Collection ID
- Name
nametext - Collection display name
- Description
descriptiontext - Optional collection description
- Icon
icontext - Optional collection icon
- Color
colortext - Optional collection color
- Cover image URL
cover_image_urltext - Optional fal-hosted cover image URL for the collection
- Filters
filterstext - 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 ID
tag_idtextRequired - Tag ID
- Name
nametext - 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
- Limit
limitnumber - Maximum number of items to return. Actual maximum depends on query type and expansion parameters.At least 1.0.
- Cursor
cursortext - Pagination cursor from previous response. Encodes the page number.
- Start
startdate and time - Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
- End
enddate 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
timezonetext - Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed.
- Timeframe
timeframetext - 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_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. - Source
sourcetext - 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_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 ID
api_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 username
login_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
- Tag
tagtext - 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
expandtext - 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": []
}
}