Falai/models
@webframp/falai/modelsv2026.10.21.1
01README
fal.ai Models — model catalog, pricing, analytics, usage, billing events, request search
02Release Notes
2026.10.21.1
Changed: The README, the apiToken description and the missing-key error
now direct you to store the fal.ai API key in a vault
(swamp vault put falai API_KEY) and wire it with
--global-arg 'apiToken=${{ vault.get("falai", "API_KEY") }}'. The README
previously showed --global-arg apiToken=FAL_API_KEY, which invited passing the
key as a literal. The FAL_KEY environment variable is still read as a
fallback, but it is not redacted and is not recommended.
No method behavior changed. Stored resources need no migration.
03Behaviors
@webframp/falai/modelsv2026.10.21.1falai/models.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiToken? | string | fal.ai API key. Wire it with ${{ vault.get("falai", "API_KEY") }}; never pass the literal value. The FAL_KEY environment variable is read as a fallback, but it is not redacted and is not recommended. |
fn get_model_insights(endpoint_id?: union, q?: string, limit?: number)
Published model insights and weekly statistics (beta)
| Argument | Type | Description |
|---|---|---|
| endpoint_id? | union | Model endpoint IDs to inspect. Repeat the parameter for multiple models; provide endpoint_id or q. |
| q? | string | Task description used to search published model guidance; provide q or endpoint_id. |
| limit? | number | Maximum number of account-visible models to return. |
fn get_models(limit?: number, cursor?: string, endpoint_id?: union, q?: string, category?: string, status?: enum, sort?: enum, expand?: union)
Model search
| Argument | Type | Description |
|---|---|---|
| limit? | number | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. |
| cursor? | string | Pagination cursor from previous response. Encodes the page number. |
| endpoint_id? | union | 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? | string | Free-text search query to filter models by name, description, or category |
| category? | string | Filter by category (e.g., 'text-to-image', 'image-to-video', 'training') |
| status? | enum | Filter models by status - omit to include all statuses |
| sort? | enum | 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. |
| expand? | union | 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) |
fn get_pricing(endpoint_id?: union)
Pricing
| Argument | Type | Description |
|---|---|---|
| endpoint_id? | union | 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 |
fn estimate_pricing(body: union)
Estimate cost
| Argument | Type | Description |
|---|---|---|
| body | union |
fn get_usage(limit?: number, cursor?: string, start?: union, end?: union, timezone?: string, timeframe?: enum, bound_to_timeframe?: enum, source?: enum, endpoint_id?: union, api_key_id?: union, login_username?: union, tag?: union, expand?: union)
Usage
| Argument | Type | Description |
|---|---|---|
| limit? | number | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. |
| cursor? | string | Pagination cursor from previous response. Encodes the page number. |
| start? | union | Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago. |
| end? | union | 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? | string | Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed. |
| timeframe? | enum | Aggregation timeframe for timeseries data (auto-detected from date range if not specified). Auto-detection uses: minute (<2h), hour (<2d), day (<64d), week (<183d), month (>=183d). |
| bound_to_timeframe? | enum | 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. |
| source? | enum | 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'. |
| endpoint_id? | union | 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? | union | 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? | union | 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? | union | 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? | union | 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. |
fn get_analytics(limit?: number, cursor?: string, start?: union, end?: union, timezone?: string, timeframe?: enum, bound_to_timeframe?: enum, endpoint_id?: union, expand?: union)
Analytics
| Argument | Type | Description |
|---|---|---|
| limit? | number | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. |
| cursor? | string | Pagination cursor from previous response. Encodes the page number. |
| start? | union | Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago. |
| end? | union | 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? | string | Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed. |
| timeframe? | enum | Aggregation timeframe for timeseries data (auto-detected from date range if not specified). Auto-detection uses: minute (<2h), hour (<2d), day (<64d), week (<183d), month (>=183d). |
| bound_to_timeframe? | enum | 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. |
| endpoint_id? | union | 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? | union | 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. |
fn get_billing_events(limit?: number, cursor?: string, start?: union, end?: union, source?: enum, endpoint_id?: union, request_id?: union, tag?: union, api_key_id?: union, login_username?: union, expand?: union)
Billing Events
| Argument | Type | Description |
|---|---|---|
| limit? | number | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. |
| cursor? | string | Pagination cursor from previous response. Encodes the page number. |
| start? | union | Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago. |
| end? | union | 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. |
| source? | enum | Data source. 'billed' is the default billed-event feed. 'tagged-billed' reads the tagged billing-event pivot instead, populating each row's 'tags' and enabling the 'tag' filter; it requires tagged reporting to be enabled for the account, and recent events are delayed relative to 'billed'. |
| endpoint_id? | union | 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 |
| request_id? | union | Filter by specific request ID(s). Accepts 1-50 request IDs. Supports comma-separated values: ?request_id=req1,req2 or array syntax: ?request_id=req1&request_id=req2 |
| tag? | union | 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. |
| api_key_id? | union | 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? | union | 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 |
| expand? | union | Data to include in the response. Use 'auth_method' for a formatted authentication method label, and 'auth_method_structured' for a machine-readable auth method object (detail, api_key_id, login_username). |
fn delete_request_payloads(request_id: string)
Delete request payloads
| Argument | Type | Description |
|---|---|---|
| request_id | string | Unique identifier for the request (UUID format) |
fn list_requests_by_endpoint(limit?: number, cursor?: string, endpoint_id?: union, start?: union, end?: union, status?: enum, request_id?: string, expand?: union, sort_by?: enum)
List requests by endpoint(s)
| Argument | Type | Description |
|---|---|---|
| limit? | number | Number of items to return per page (max 100) |
| cursor? | string | Pagination cursor encoding the page number |
| endpoint_id? | union | 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? | union | Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago. |
| end? | union | 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? | enum | Filter by request status |
| request_id? | string | Filter by specific request ID |
| expand? | union | Fields to expand in the response. Use payloads to include input and output payloads. |
| sort_by? | enum | Sort results by end time or duration |
fn search_requests(limit?: number, cursor?: string, query?: string, image_url?: string, video_url?: string, endpoint_id?: union, endpoint?: string, exclude_api_requests?: boolean, only_api_requests?: boolean, min_similarity?: number)
Search Requests
| Argument | Type | Description |
|---|---|---|
| limit? | number | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. |
| cursor? | string | Pagination cursor from previous response. Encodes the page number. |
| query? | string | Text search query for semantic search. Mutually exclusive with image_url and video_url. |
| image_url? | string | Image URL for similarity search. Mutually exclusive with query and video_url. |
| video_url? | string | Video URL for similarity search. Mutually exclusive with query and image_url. |
| endpoint_id? | union | Filter by one or more fal endpoints to scope request history. Accepts comma-separated or repeated values (1-50 IDs). |
| endpoint? | string | Deprecated: use `endpoint_id`. Single-endpoint filter retained for backward compatibility. If both are provided, `endpoint_id` wins. |
| exclude_api_requests? | boolean | Exclude requests made via API keys (only show playground/UI requests). Mutually exclusive with only_api_requests. |
| only_api_requests? | boolean | Only include requests made via API keys. Mutually exclusive with exclude_api_requests. |
| min_similarity? | number | Minimum similarity score (0-1) for semantic search results. Only applies when query or image_url is provided. |
Resources
get_model_insights(infinite)— Published model insights and weekly statistics (beta)
get_models(infinite)— Model search
get_pricing(infinite)— Pricing
estimate_pricing(infinite)— Estimate cost
get_usage(infinite)— Usage
get_analytics(infinite)— Analytics
get_billing_events(infinite)— Billing Events
requests_by_endpoint(infinite)— List requests by endpoint(s)
search_requests(infinite)— Search Requests
04Previous Versions
2026.10.14.1Apache-2.0(was none)
2026.10.14.1
Fixed: Methods that write a singleton resource failed on current swamp with
Data name 'latest' is reserved for internal use.
Changed: Singleton get and action methods now write their data under
estimate_pricing-current instead of latest. Anything that read
data.latest("<model>", "latest") or queried name == "latest" must use the
new name.
Upgrade note: Data previously stored under latest is not migrated; re-run
the method to populate the new name. No attribute schemas changed.
Added: The manifest now declares license: Apache-2.0 (SPDX). The registry quality rubric scores a declared license separately from the bundled LICENSE.md.
2026.09.25.1
2026.09.25.1
Added: Usage insights and billing events support tagged reporting through
new source selectors and tag filters.
Changed: Tagged reporting responses now expose the request tag key/value map when returned by fal.ai.
2026.09.18.1
2026.09.18.1
Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the
repo. No behavioral changes in this extension.
2026.09.17.2
2026.09.17.2
Add get_model_insights method for the new /models/{id}/insights endpoint. Also: response schema fields are now generated as optional/nullable-optional regardless of the spec's required list, so reading a resource stored under an older model version no longer throws when the live API has since added required fields (quantity/unit on billing events); list methods with a documented default page size now use it to detect truncation when the caller omits limit.
Modified 1 behaviors
2026.09.15.1
2026.09.15.1
Changed: Bump zod 4.4.3 → 4.6.5
2026.09.10.4
Fixed:
- Resource instance names for get/update methods with two or more path
parameters (e.g.
get_app_queue_info(owner, name),get_workflow(username, workflow_name)) were built by joining raw values with"_". Two distinct owner/name pairs that split differently around an underscore (e.g."john"/"doe_app"and"john_doe"/"app") produced the identical instance name and collided. Multi-param instance names are now derived from a hash of the JSON-encoded parameter tuple, which delimits each part unambiguously.
Upgrade note: No schema changes. All fixes are internal to method execution; existing stored resources are unaffected.
2026.09.10.4
2026.09.10.4
Fixed:
- Resource instance names for get/update methods with two or more path
parameters (e.g.
get_app_queue_info(owner, name),get_workflow(username, workflow_name)) were built by joining raw values with"_". Two distinct owner/name pairs that split differently around an underscore (e.g."john"/"doe_app"and"john_doe"/"app") produced the identical instance name and collided. Multi-param instance names are now derived from a hash of the JSON-encoded parameter tuple, which delimits each part unambiguously.
Upgrade note: No schema changes. All fixes are internal to method execution; existing stored resources are unaffected.
05Stats
A
100 / 100
Downloads
36
Archive size
24.9 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned
06Platforms
07Labels