Falai/models
@webframp/falai/modelsv2026.09.10.4
01README
fal.ai Models — model catalog, pricing, analytics, usage, billing events, request search
02Release Notes
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.
03Models
@webframp/falai/modelsv2026.09.10.4falai/models.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiToken? | string | fal.ai API key; overrides the FAL_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault. |
fn get_models(limit?: number, cursor?: string, endpoint_id?: union, q?: string, category?: string, status?: 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 |
| 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, endpoint_id?: union, api_key_id?: union, login_username?: 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. |
| 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 |
| 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, endpoint_id?: union, request_id?: 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. |
| 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 |
| 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_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
04Stats
A
100 / 100
Downloads
0
Archive size
25.1 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
- License declared1/1earned
- Verified public repository2/2earned
05Platforms
06Labels