A fal.ai MCP server/CLI exposing 66 tools for model discovery, pricing, generation, queue operations, asset management, storage controls, and account/organization data.
Search and inspect current fal.ai model endpoints, schemas, and unit pricing.
Estimate costs and review usage, analytics, billing events, and account/org billing.
Run models synchronously or submit queued image/video/model generation jobs.
Read job status/results and request cancellation without auto-polling or retries.
Upload local files to fal CDN and manage assets, collections, tags, characters, favorites, and lineage.
Read and change CDN file ACLs, storage lifecycle settings, and create private signed URLs.
Preview and submit exact reviewed generation batches with schema/price/hash checks.
List local account profiles and inspect native platform operation schemas.
Paid/mutating operations require explicit confirmation; reads and local-only helpers are available without mutation approval.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@fal.ai MCP Server find the latest fal.ai image model and show its pricing"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
fal.ai MCP server and CLI for Codex and AI agents. 66 shared tools for current models, queue receipts, Assets and storage controls, private account profiles and exact reviewed generation batches.
One package provides a task CLI, local stdio MCP and versioned desktop bundle. Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI. Complete setup: navid.me.
The terminal illustrates actual commands, not a recorded provider account session. Node 22+ is required for manual installs; private account access, model eligibility and generation credits remain separate.
A terminal or shell agent calls only the requested task.
npx -y --package @thenavidm/fal-ai-mcp-cli@latest fal-ai-cli search-models --limit 1 --agentRegister the local stdio package with private credentials; Codex setup comes first.
codex mcp add fal-ai --env FAL_TOKEN_FILE=/absolute/private/fal.txt -- npx -y @thenavidm/fal-ai-mcp-cli@latestUse the CLI for task-specific shell discovery/compact selected output, or MCP for an AI client supporting local tools. Both enforce the same handlers, validation and approval policy.
Related MCP server: Creatomate MCP Server
Current dynamic model/schema discovery, receipt-based queue operations and full native creative platform arguments.
Shared local confirmation/read-only policy and isolated account API keys.
Exact current-schema/unit-quote batch review and stop-on-failure receipts.
Native Assets, collection, tag, character and CDN ACL/retention controls.
Complete Codex/client/OS/desktop setup, current comparisons, version history and accordion FAQs.
Section | What it covers |
What you can ask it | |
Quick install | |
Set up fal.ai access | |
Connect your client | |
Check it works | |
Output, flags and exit codes | |
MCP or CLI and token cost | |
Every tool and argument | |
Model and asset workflows | |
Exact reviewed batches and pagination | |
Several private accounts | |
Writing safely | |
How the two surfaces work | |
Your data | |
Environment variables | |
Updates and removal | |
Troubleshooting | |
API coverage and comparisons | |
Versions and migration | |
FAQ |
Find exact current image, video, audio or 3D endpoint IDs and inspect their native schemas.
Read unit pricing, estimate quantities deliberately and inspect the intended account's billable usage.
Submit only the approved native model payload, keep its request ID and read progress/results once.
Review several ordered generations against current schemas and prices, then submit only that matching approved batch.
Browse and manage requested Assets, collections, tags and characters using native fields.
Read or explicitly change CDN ACL/retention settings and save a signed access URL privately.
Actual shared discovery exposes 66 tools: 32 reads and 34 confirmed operations. It wraps 53 selected current native platform operations plus 13 creative/account/batch helpers. All nine legacy tool names remain, with deliberate 2.0 breaking argument/behavior corrections documented below. Generic model support is conditional on discoverable/compilable current JSON schemas, credentials and model access; it is not a guarantee that every current/future endpoint works.
npm install -g @thenavidm/fal-ai-mcp-cli@latest
fal-ai-cli --version
fal-ai-cli tools
fal-ai-cli schema submit-job
fal-ai-cli loginNode 22+ for manual CLI/local MCP. INSTALL.md covers every declared client/OS and the versioned desktop bundle. Official genmedia and Python fal are separate binaries; ours is fal-ai-cli.
Sign into the intended fal account. Confirm which personal/team account owns the credits and key before creating or copying it.
Use only the provider permissions needed for the requested work. Model execution, Assets, billing and organization reads have different requirements. A working model read does not prove asset/admin permissions.
Store FAL_KEY in private user/client environment settings or FAL_TOKEN_FILE as an absolute token-only file outside Git. On macOS/Linux use an owner-private directory and regular non-symlink 0600 file, at most 64 KiB. On Windows restrict ACLs to yourself; POSIX mode does not prove Windows ACLs.
Run fal-ai-cli doctor for local settings; doctor --network deliberately reads one model with limit=1. It reports count only, does not spend credits and does not prove the authenticated owner. Public model discovery can work without a key.
Inspect the exact current model schema and unit pricing before approving generation. Use a queue receipt to read progress/results; never submit again to check progress. Do not generate paid media, create keys or delete assets just to test installation.
FAL_ACCOUNTS is a private JSON array of unique {name,api_key,token_file} profiles; FAL_DEFAULT_ACCOUNT selects an exact label. A selected token file overrides only that profile's key. Explicit profiles never inherit FAL_KEY or another profile after missing credentials or a 401/403. Labels are not verified fal owners. Tokens cache until process restart; rotate/revoke at fal and restart clients.
This wrapper uses API keys with Authorization: Key on fixed api.fal.ai, queue.fal.run, fal.run and the SDK-pinned rest.fal.ai upload-initiation origin. No credential goes on the CDN upload PUT. No hosted OAuth, .env loading, SDK key-ID/secret environment inheritance, official genmedia config import, session cookie import, telemetry or automatic background update exists. login prints setup instructions and does not save credentials or start sign-in.
The current model-generation MCP uses OAuth at https://mcp.fal.ai/mcp-relay. Its Active MCP account setting routes new uploads/generations; old jobs remain with their original account, and failed selected-account access does not fall back to personal credits. This is already an official isolation feature. API-key clients, including this package and genmedia, use the key's owning account separately.
The separate Platform MCP at https://api.fal.ai/v1/mcp/platform uses API keys and is read-only account/serverless tooling. Documentation MCP at https://fal.ai/docs/mcp searches public docs without model execution. The old March launch article/key-based endpoint and its nine tools are historical evidence, not the current OAuth setup or tool count.
The AGPL wrapper is free; fal generation credits, endpoint pricing, output quantities, model eligibility and concurrency limits apply. Unit pricing and cost estimates are different from completed billable usage. Unit quotes can scale with resolution, duration, output count or GPU time; a batch of ten requests is not a ten-output or ten-dollar limit. No local budget guarantee or credit reservation is promised.
No requests automatically retry, including reads, 429, failed uploads, timeouts or 5xx. Respect current provider throttling guidance before deliberately repeating a read. A timeout after a paid POST may have spent credits without returning a request ID: inspect fal history before another submission. Responses cap at 5 MiB and JSON requests at 1 MiB. One native list page is returned with its real cursor; there is no invented all-pages backup.
Generated and uploaded CDN media may be public under account defaults. The local generation default sends X-Fal-Store-IO:0 to disable provider JSON input/output storage; CDN media access and expiration are separate. Explicit store_io:true allows native payload storage. Native lifecycle JSON can specify expiration_duration_seconds and initial_acl with default allow/forbid/hide and nickname rules. Unknown nicknames may be silently dropped by fal; an ACL request is not proof of actual external visibility.
Local upload sends only the selected regular file, 1 byte–20 MiB, through upload initiation and one restricted fal.media PUT. Larger/multipart/remote-URL upload conveniences belong to the official clients; no retry or automatic generation occurs here. Sign-file URL credentials are saved only into an exclusive new private JSON file. Existing files are never overwritten. Keep parent directory and Windows ACLs private; a signature is access authority even if its field says URL.
Revoke the exact key at fal, replace private settings/files and restart every process. Revoke official OAuth connections separately. Removing the package/client registration does not cancel jobs, undo asset mutations, delete provider payloads/CDN files, revoke credentials or refund generation credits. Inspect receipts and provider state before explicitly requested cleanup.
Codex setup comes first in INSTALL.md, followed by Claude Code, Claude Desktop extension/manual stdio, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, Cline, Docker and other local stdio clients on macOS/Windows/Linux. Use private key settings available to the actual local/remote runtime. GUI apps may not inherit terminal environment; restart after changing settings.
This package provides local stdio. Remote-only clients use the provider-hosted OAuth relay. Skills are optional agent guidance; installing npm does not register SKILL.md automatically. No Claude Code installation is needed for Codex.
codex mcp add fal-ai --env FAL_TOKEN_FILE=/absolute/private/fal.txt -- npx -y @thenavidm/fal-ai-mcp-cli@latestfal-ai-cli --version
fal-ai-cli tools
fal-ai-cli list-accounts --agent
fal-ai-cli doctor
fal-ai-cli doctor --network
fal-ai-cli search-models --limit 1 --agent
fal-ai-cli get-model-info --model-id fal-ai/flux/dev --agentPublic model discovery/schema reads have been verified without credentials or generation credits. Private doctor --network reads one model with count only; model metadata can be public, so that result is not an account-owner or all-permissions test. Model runs, authenticated Assets and real queue outcomes require separate live-account verification. Never use a paid or destructive call as an install smoke test.
Both surfaces return provider JSON through the same handlers. Queue submission returns request_id receipts with completed:false. get_job_status and get_job_result read once; cancel receipts do not prove stopped processing/refunds. Synchronous run timeouts can leave an unknown paid outcome. No returned media is downloaded or embedded automatically. Signed access credentials go only to a new exclusive private file; console responses contain saved-file metadata.
Use the actual task schema. Repeated primitive array flags pass one value each; repeated --tasks values are individual JSON task objects. Complete native body unions use --payload JSON or a private --payload-file, mutually exclusive with flat body flags. Native query/header/body names remain visible in the schema; kebab-case flags come from the shared house bridge.
fal-ai-cli search-models --limit 5 --agent --select models,next_cursor
fal-ai-cli submit-job --help
fal-ai-cli schema estimate-pricingFlag | Behavior |
--agent | Compact JSON and no prompts; never confirms a write |
--confirm | Explicit approval for exactly the requested operation |
--account LABEL | Exact private API-key profile |
--select a,b.c | Local output field selection |
--payload / --payload-file | Native body, mutually exclusive with other body routes |
--tasks JSON | Repeat an individual ordered generation object |
--review-sha256 HASH | Exact preview hash before batch submission |
--output-file PATH | New private signed-URL credential file |
Exit | Meaning |
0 | Handler success/receipt; submission does not mean completed generation |
1 | Unexpected error |
2 | Invalid input or refused policy operation, an unknown command or a hidden write |
3 | Not found |
4 | Provider authentication/permissions |
5 | Provider/network/unknown outcome |
7 | Rate limit |
10 | Missing or invalid local account credentials/configuration |
The tools, schemas, handlers and write guard are shared. MCP clients discover local tools; shell agents can inspect command help/schema only when needed and select smaller result fields. Context cost depends on client tool discovery, loaded descriptions/schemas, prompts and output size.
Measured on 2026-10-05 against 2.0.2, the same day, with Claude Code 2.1.286 on Claude Opus 5.5 (one short prompt with and without the server connected, the difference read from the API's own usage figures) and Codex 0.159.3 on gpt-6.1-sol:
Cost | 2.0.2 | 3.0.0 |
Claude Code, every tool loaded, every message | 41,570 | 40,519 |
Claude Code's default, tool search, every message | 1,316 | 1,319 |
| 1,290 | 1,340 |
Codex over the CLI, one task, median of five | 127,484 | 105,371 |
Codex over MCP, the same task, median of five | 77,462 | 77,596 |
The task was "find the command that estimates what a generation will cost, and the flags it requires". Over the CLI, three 2.0.2 runs guessed an estimate command that does not exist, because 2.0.2's help listed none, and every extra step carries the whole conversation forward; every 3.0.0 run asked which. Over MCP, Codex prints its own TypeScript rendering of the tool list and keeps its first and last 20,000 characters or so: the whole rendering is 532 tokens shorter on 3.0.0, but the part Codex keeps holds about 57 more, which each later request carries. SKILL.md costs 50 more because it now says how approval works over MCP and lists every exit code.
Tool-list bytes or characters divided by four are not API usage, and no other offering was measured.
search_modelsUnified endpoint for discovering model endpoints. Supports three usage modes: 1. List Mode (no parameters): Paginated list of all available model endpoints with minimal metadata. 2. Find Mode (endpoint_id parameter): Retrieve specific model endpoint(s) by ID. Supports single or multiple IDs. 3. Search Mode (search parameters): Filter models by free-text query, category, or status. Expansion: Use expand to include additional data in each model object: - openapi-3.0 : full OpenAPI 3.0 schema in the openapi field - enterprise_status : enterprise readiness status (ready or pending) in the enterprise_status field Examples of endpoint_id values: - fal-ai/flux/dev - fal-ai/wan/v2.2-a14b/text-to-video - fal-ai/minimax/video-01/image-to-video - fal-ai/hunyuan3d-v21 See fal.ai Model APIs for more details. Authentication: Optional. Providing an API key grants higher rate limits. Common Use Cases: - Browse available models for integration - Retrieve metadata for specific endpoints - Search for models by category or keywords - Get OpenAPI schemas for code generation - Build model selection interfaces
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| No; body/guard requirements still apply | JSON | 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 |
| No; body/guard requirements still apply | string | Free-text search query to filter models by name, description, or category |
| No; body/guard requirements still apply | string | Filter by category (e.g., 'text-to-image', 'image-to-video', 'training') |
| No; body/guard requirements still apply | string | Filter models by status - omit to include all statuses enum: |
| No; body/guard requirements still apply | JSON | 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) |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
input.endpoint_id
input.endpoint_id anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.endpoint_id anyOf branch 2
input.endpoint_id.anyOf2[]
Native JSON value; inspect the full schema for validation.
input.expand
input.expand anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.expand anyOf branch 2
input.expand.anyOf2[]
Native JSON value; inspect the full schema for validation.
get_pricingReturns 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. Authentication: Required. Users must provide a valid API key. Custom pricing or discounts may be applied based on account status. Common Use Cases: - Display pricing in user interfaces - Compare pricing across different models - Build cost estimation tools - Check current billing rates See fal.ai pricing for more details.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | JSON | 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 |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
input.endpoint_id
input.endpoint_id anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.endpoint_id anyOf branch 2
input.endpoint_id.anyOf2[]
Native JSON value; inspect the full schema for validation.
estimate_pricingComputes cost estimates using one of two methods: 1. Historical API Price (historical_api_price): - Based on historical pricing per API call from past usage patterns - Takes call_quantity (number of API calls) per endpoint - Useful for estimating based on actual historical usage patterns - Example: "How much will 100 calls to flux/dev cost?" 2. Unit Price (unit_price): - Based on unit price × expected billing units from pricing service - Takes unit_quantity (number of billing units like images/videos) per endpoint - Useful when you know the expected output quantity - Example: "How much will 50 images from flux/dev cost?" Authentication: Required. Users must provide a valid API key. Custom pricing or discounts may be applied based on account status. Common Use Cases: - Pre-calculate costs for batch operations - Display cost estimates in user interfaces - Budget planning and cost optimization See fal.ai pricing for more details.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | JSON | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.payload
input.payload oneOf branch 1
Argument | Required | Type | Details |
| Yes | string | Estimate type: historical API pricing based on past usage patterns enum: |
| Yes | object | Map of endpoint IDs to call quantities |
input.payload.oneOf1.endpoints
input.payload.oneOf1.endpoints.{key}
Argument | Required | Type | Details |
| Yes | integer | Number of API calls to estimate (regardless of units per call) minimum: |
input.payload oneOf branch 2
Argument | Required | Type | Details |
| Yes | string | Estimate type: unit price calculation based on billing units enum: |
| Yes | object | Map of endpoint IDs to unit quantities |
input.payload.oneOf2.endpoints
input.payload.oneOf2.endpoints.{key}
Argument | Required | Type | Details |
| Yes | number | Number of billing units expected (e.g., number of images, videos, etc.) minimum: |
get_usageReturns 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 − cost_discount). Key Features: - Usage data for all endpoints or filtered by specific endpoint(s) - Flexible date range filtering - User-specific usage tracking - Detailed usage line items with unit quantity, price, and discount breakdown - Paginated results for large datasets Common Use Cases: - Generate usage reports for all endpoints or specific models - Track usage patterns - Monitor endpoint usage across different auth methods - Build usage dashboards and visualizations See fal.ai docs for more details.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| No; body/guard requirements still apply | JSON | Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago. |
| No; body/guard requirements still apply | JSON | 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. |
| No; body/guard requirements still apply | string | Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed. default: |
| No; body/guard requirements still apply | string | 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). enum: |
| No; body/guard requirements still apply | string | 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. enum: |
| No; body/guard requirements still apply | JSON | 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 |
| No; body/guard requirements still apply | JSON | 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 |
| No; body/guard requirements still apply | JSON | 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 |
| No; body/guard requirements still apply | JSON | 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. default: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
input.start
input.start anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.start anyOf branch 2
Native JSON value; inspect the full schema for validation.
input.end
input.end anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.end anyOf branch 2
Native JSON value; inspect the full schema for validation.
input.endpoint_id
input.endpoint_id anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.endpoint_id anyOf branch 2
input.endpoint_id.anyOf2[]
Native JSON value; inspect the full schema for validation.
input.api_key_id
input.api_key_id anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.api_key_id anyOf branch 2
input.api_key_id.anyOf2[]
Native JSON value; inspect the full schema for validation.
input.login_username
input.login_username anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.login_username anyOf branch 2
input.login_username.anyOf2[]
Native JSON value; inspect the full schema for validation.
input.expand
input.expand anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.expand anyOf branch 2
input.expand.anyOf2[]
Native JSON value; inspect the full schema for validation.
get_analyticsTime-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. Metric Selection: You must specify which metrics to include using the expand query parameter. Only requested metrics will be populated in the response, allowing you to optimize query performance and data transfer. Available Metrics: The expand parameter accepts these values, grouped by category: Volume - request_count: Total number of requests in the time bucket - success_count: Successful requests (2xx responses) - user_error_count: User errors (4xx responses) - error_count: Server errors (5xx responses) Error type breakdown - startup_error_count: Startup errors (startup timeout, scheduling failure) - connection_error_count: Connection errors (timeout, disconnected, refused) - timeout_error_count: Request timeout errors - runtime_error_count: Runtime errors (internal error, server error) Queue / prepare latency - p50_prepare_duration, p75_prepare_duration, p90_prepare_duration, p95_prepare_duration, p99_prepare_duration: Time from request submission until execution starts Request execution latency - p25_duration, p50_duration, p75_duration, p90_duration, p95_duration, p99_duration: Time spent processing the request Cold boot - cold_boot_count: Requests with cold boot (startup > 1s) - p50_cold_boot_duration, p75_cold_boot_duration, p90_cold_boot_duration: Cold boot duration percentiles Billing - total_billable_duration: Aggregate billed execution time Key Features: - Selective metric inclusion via expand parameter - Performance metrics (latency percentiles, duration stats) - Reliability metrics (success/error rates, request counts) - Error type breakdown (startup, connection, timeout, runtime) - Cold boot metrics (count, latency percentiles) - Billing duration tracking - Time-bucketed data for trend analysis - Single or multi-model analytics - Flexible date range and timeframe options Common Use Cases: - Monitor model performance and reliability - Generate performance dashboards - Analyze latency trends and patterns - Track error rates and success metrics See Queue API docs for more details.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| No; body/guard requirements still apply | JSON | Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago. |
| No; body/guard requirements still apply | JSON | 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. |
| No; body/guard requirements still apply | string | Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed. default: |
| No; body/guard requirements still apply | string | 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). enum: |
| No; body/guard requirements still apply | string | 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. enum: |
| Yes | JSON | 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 |
| No; body/guard requirements still apply | JSON | 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. default: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
input.start
input.start anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.start anyOf branch 2
Native JSON value; inspect the full schema for validation.
input.end
input.end anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.end anyOf branch 2
Native JSON value; inspect the full schema for validation.
input.endpoint_id
input.endpoint_id anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.endpoint_id anyOf branch 2
input.endpoint_id.anyOf2[]
Native JSON value; inspect the full schema for validation.
input.expand
input.expand anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.expand anyOf branch 2
input.expand.anyOf2[]
Native JSON value; inspect the full schema for validation.
get_billing_eventsReturns paginated individual billing event records with filters for endpoint and date range. Each record includes the request ID, timestamp, endpoint, output units billed, and a cost breakdown in USD (cost_subtotal, cost_discount, cost_total; cost_estimate_nano_usd carries cost_total in nano USD). Key Features: - Individual billing event records for each API request - Per-request cost breakdown before and after discounts - Flexible date range filtering - Optional endpoint filtering - Cursor-based pagination for efficient large dataset queries - Limited to 10000 records per page for performance - Date range capped at 90 days per request Common Use Cases: - Audit individual billing events - Track request patterns and volumes - Debug specific requests by ID - Monitor billing unit consumption per request See fal.ai docs for more details.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| No; body/guard requirements still apply | JSON | Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago. |
| No; body/guard requirements still apply | JSON | 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. |
| No; body/guard requirements still apply | JSON | 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 |
| No; body/guard requirements still apply | JSON | 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 |
| No; body/guard requirements still apply | JSON | 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 |
| No; body/guard requirements still apply | JSON | 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 |
| No; body/guard requirements still apply | JSON | 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). |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
input.start
input.start anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.start anyOf branch 2
Native JSON value; inspect the full schema for validation.
input.end
input.end anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.end anyOf branch 2
Native JSON value; inspect the full schema for validation.
input.endpoint_id
input.endpoint_id anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.endpoint_id anyOf branch 2
input.endpoint_id.anyOf2[]
Native JSON value; inspect the full schema for validation.
input.request_id
input.request_id anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.request_id anyOf branch 2
input.request_id.anyOf2[]
Native JSON value; inspect the full schema for validation.
input.api_key_id
input.api_key_id anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.api_key_id anyOf branch 2
input.api_key_id.anyOf2[]
Native JSON value; inspect the full schema for validation.
input.login_username
input.login_username anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.login_username anyOf branch 2
input.login_username.anyOf2[]
Native JSON value; inspect the full schema for validation.
input.expand
input.expand anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.expand anyOf branch 2
input.expand.anyOf2[]
Native JSON value; inspect the full schema for validation.
delete_request_payloadsDeletes the IO payloads and associated CDN output files for a specific request. Important: - Only output CDN files are deleted (input files may be used by other requests) - This action is irreversible - Requires authentication with an admin API key What gets deleted: - Request input/output payload data - CDN-hosted output files (images, videos, etc.) What is NOT deleted: - Input CDN files (may be referenced by other requests) Response: - Returns deletion status for each CDN file - Each result includes the file link and any error that occurred Idempotency: - Optional Idempotency-Key header prevents duplicate deletions on retries - Responses cached for 10 minutes per unique key See fal.ai docs for more details about request payloads.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Unique identifier for the request (UUID format) format: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
list_requests_by_endpointLists requests for one or more endpoints (same endpoint_id style as usage/explore: comma-separated or repeated query params, up to 50 IDs). Authentication: Requires API key (user or enterprise). Filters: - Time range via start / end. If start is omitted, defaults to the last 24 hours : unless request_id is provided, in which case the default start bound is widened to 90 days. - Status (success, error, user_error) - Request ID - Pagination via cursor/limit (limit defaults to 50, max 100) Sorting: - By end time (default) or duration Expansions: - Include payloads by adding expand=payloads
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | integer | Number of items to return per page (max 100) minimum: |
| No; body/guard requirements still apply | string | Pagination cursor encoding the page number |
| Yes | JSON | 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 |
| No; body/guard requirements still apply | JSON | Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago. |
| No; body/guard requirements still apply | JSON | 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. |
| No; body/guard requirements still apply | string | Filter by request status enum: |
| No; body/guard requirements still apply | string | Filter by specific request ID format: |
| No; body/guard requirements still apply | JSON | Fields to expand in the response. Use payloads to include input and output payloads. |
| No; body/guard requirements still apply | string | Sort results by end time or duration enum: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
input.endpoint_id
input.endpoint_id anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.endpoint_id anyOf branch 2
input.endpoint_id.anyOf2[]
Native JSON value; inspect the full schema for validation.
input.start
input.start anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.start anyOf branch 2
Native JSON value; inspect the full schema for validation.
input.end
input.end anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.end anyOf branch 2
Native JSON value; inspect the full schema for validation.
input.expand
input.expand anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.expand anyOf branch 2
input.expand.anyOf2[]
Native JSON value; inspect the full schema for validation.
search_requestsSearch, filter, and browse your request history. Supports three modes: 1. Semantic Search (query, image_url, or video_url parameter): Find visually or conceptually similar results using AI embeddings. Provide a text query for text-to-image search, an image URL for image-to-image similarity search, or a video URL for video-to-image similarity search. 2. Filtered Browse (no query, image_url, or video_url): Browse request history with hard filters. Returns results ordered by creation date (newest first). 3. Semantic + Filters (search params AND filter params): Combine semantic search with hard filters. Filters narrow the candidate set before ranking by similarity. Filter Options: - endpoint_id: Filter by one or more fal endpoints (comma-separated or repeated, up to 50 IDs) - exclude_api_requests / only_api_requests: Filter by request source Examples: - Semantic text search: ?query=sunset+landscape - Image similarity: ?image_url=https://...&min_similarity=0.5 - Filtered search: ?query=portrait&endpoint_id=fal-ai/flux/dev - Browse across multiple endpoints: ?endpoint_id=fal-ai/flux/dev,fal-ai/flux/schnell
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| No; body/guard requirements still apply | string | Text search query for semantic search. Mutually exclusive with image_url and video_url. |
| No; body/guard requirements still apply | string | Image URL for similarity search. Mutually exclusive with query and video_url. |
| No; body/guard requirements still apply | string | Video URL for similarity search. Mutually exclusive with query and image_url. |
| No; body/guard requirements still apply | JSON | Filter by one or more fal endpoints to scope request history. Accepts comma-separated or repeated values (1-50 IDs). |
| No; body/guard requirements still apply | string | Deprecated: use |
| No; body/guard requirements still apply | boolean | Exclude requests made via API keys (only show playground/UI requests). Mutually exclusive with only_api_requests. |
| No; body/guard requirements still apply | boolean | Only include requests made via API keys. Mutually exclusive with exclude_api_requests. |
| No; body/guard requirements still apply | ['number', 'null'] | Minimum similarity score (0-1) for semantic search results. Only applies when query or image_url is provided. minimum: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
input.endpoint_id
input.endpoint_id anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.endpoint_id anyOf branch 2
input.endpoint_id.anyOf2[]
Native JSON value; inspect the full schema for validation.
list_workflowsList workflows for the authenticated user with optional search and filtering. Features: - Paginated results with cursor-based pagination - Search by workflow name or title - Filter by model endpoints used in the workflow Authentication: Required. Returns only workflows owned by the authenticated user. Common Use Cases: - Display user's workflow library - Search for specific workflows - Find workflows using particular models
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| No; body/guard requirements still apply | string | Search by workflow name or title |
| No; body/guard requirements still apply | JSON | Filter by model endpoint IDs used in the workflow. Can be a single value or comma-separated values. |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
input.used_endpoint_ids
input.used_endpoint_ids anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.used_endpoint_ids anyOf branch 2
input.used_endpoint_ids.anyOf2[]
Native JSON value; inspect the full schema for validation.
create_workflowCreate a new workflow owned by the authenticated user. Authentication: Required. Common Use Cases: - Save a newly built workflow - Programmatically provision workflows Note: Workflow names must be unique within your namespace. Creating a workflow with a name you already use returns a 400 validation error.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Unique workflow name/slug within the user's namespace maxLength: |
| No; body/guard requirements still apply | string | Human-readable workflow title minLength: |
| No; body/guard requirements still apply | object | The workflow definition/configuration object |
| No; body/guard requirements still apply | boolean | Whether the workflow is publicly visible default: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.contents
Argument | Required | Type | Details |
| Yes | string | Internal name of the workflow definition |
| Yes | string | Workflow definition format version |
| Yes | object | Workflow nodes keyed by node id |
| Yes | object | Output field mappings keyed by output name |
| Yes | object | Input/output schema for the workflow |
| No; body/guard requirements still apply | object | Optional workflow metadata |
input.contents.nodes
input.contents.nodes.{key}
input.contents.nodes.{key}.{key}
Native JSON value; inspect the full schema for validation.
input.contents.output
input.contents.output.{key}
Native JSON value; inspect the full schema for validation.
input.contents.schema
Argument | Required | Type | Details |
| Yes | object | Input fields schema |
| Yes | object | Output fields schema |
input.contents.schema.input
input.contents.schema.input.{key}
Native JSON value; inspect the full schema for validation.
input.contents.schema.output
input.contents.schema.output.{key}
Native JSON value; inspect the full schema for validation.
input.contents.metadata
input.contents.metadata.{key}
Native JSON value; inspect the full schema for validation.
input.payload
Argument | Required | Type | Details |
| Yes | string | Unique workflow name/slug within the user's namespace maxLength: |
| Yes | string | Human-readable workflow title minLength: |
| Yes | object | The workflow definition/configuration object |
| No; body/guard requirements still apply | boolean | Whether the workflow is publicly visible default: |
input.payload.contents
Argument | Required | Type | Details |
| Yes | string | Internal name of the workflow definition |
| Yes | string | Workflow definition format version |
| Yes | object | Workflow nodes keyed by node id |
| Yes | object | Output field mappings keyed by output name |
| Yes | object | Input/output schema for the workflow |
| No; body/guard requirements still apply | object | Optional workflow metadata |
input.payload.contents.nodes
input.payload.contents.nodes.{key}
input.payload.contents.nodes.{key}.{key}
Native JSON value; inspect the full schema for validation.
input.payload.contents.output
input.payload.contents.output.{key}
Native JSON value; inspect the full schema for validation.
input.payload.contents.schema
Argument | Required | Type | Details |
| Yes | object | Input fields schema |
| Yes | object | Output fields schema |
input.payload.contents.schema.input
input.payload.contents.schema.input.{key}
Native JSON value; inspect the full schema for validation.
input.payload.contents.schema.output
input.payload.contents.schema.output.{key}
Native JSON value; inspect the full schema for validation.
input.payload.contents.metadata
input.payload.contents.metadata.{key}
Native JSON value; inspect the full schema for validation.
get_workflowGet detailed information about a specific workflow, including its full contents/definition. Authentication: Required. Common Use Cases: - Load a workflow for editing - View workflow configuration - Export workflow definition
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | string | The username of the workflow owner maxLength: |
| Yes | string | The workflow name/slug maxLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
list_assetsBrowse and semantically search fal Assets across all media, uploads, favorites, collections, tags, and character references.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| No; body/guard requirements still apply | string | Text query for hybrid semantic search |
| No; body/guard requirements still apply | string | fal-hosted image URL to use for semantic image search format: |
| No; body/guard requirements still apply | string | fal-hosted video URL to use for semantic video search format: |
| No; body/guard requirements still apply | ['array', 'null'] | Filter by one or more media types default: |
| No; body/guard requirements still apply | ['array', 'null'] | Filter by one or more indexed sources default: |
| No; body/guard requirements still apply | string | Asset library section to browse enum: |
| No; body/guard requirements still apply | string | Collection scope to browse |
| No; body/guard requirements still apply | ['array', 'null'] | Character identifiers to use as @mention semantic filters default: |
| No; body/guard requirements still apply | ['array', 'null'] | Tag IDs to filter by default: |
| No; body/guard requirements still apply | string | Whether tag filters match any tag or all tags enum: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
input.media_type
input.media_type[]
Asset media type
input.source
input.source[]
Indexed asset source
input.character_identifier
input.character_identifier[]
Native JSON value; inspect the full schema for validation.
input.tag_id
input.tag_id[]
Native JSON value; inspect the full schema for validation.
list_asset_collectionsList asset collections for the authenticated user's fal Assets library.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | integer | Maximum number of collections to return minimum: |
| No; body/guard requirements still apply | ['integer', 'null'] | Number of collections to skip minimum: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
create_asset_collectionCreate asset collection for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Collection display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection description |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection icon |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection color |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the collection format: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional parent collection ID to nest this collection under (manual collections only). Omit or null to create a top-level collection. minLength: |
| No; body/guard requirements still apply | JSON | Assets filter DSL |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.payload
Argument | Required | Type | Details |
| Yes | string | Collection display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection description |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection icon |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection color |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the collection format: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional parent collection ID to nest this collection under (manual collections only). Omit or null to create a top-level collection. minLength: |
| No; body/guard requirements still apply | JSON | Assets filter DSL |
get_asset_collectionGet asset collection for the authenticated user's fal Assets library.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
update_asset_collectionUpdate asset collection for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Collection display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection description |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection icon |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection color |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the collection format: |
| No; body/guard requirements still apply | JSON | Assets filter DSL |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Collection display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection description |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection icon |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection color |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the collection format: |
| No; body/guard requirements still apply | JSON | Assets filter DSL |
delete_asset_collectionDelete asset collection for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
get_asset_collection_hierarchyGet the nested subtree rooted at an asset collection, plus its ancestor collections ordered from the top level down to its direct parent.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
favorite_asset_collectionFavorite an asset collection for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
unfavorite_asset_collectionUnfavorite an asset collection for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
move_asset_collectionMove a manual asset collection under another collection, or to the top level. Only manual collections can be moved or act as folders; nesting is limited to 5 levels deep and cannot create a cycle.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | ['string', 'null'] | Parent collection ID to move this collection under, or null to move it to the top level. Must be a manual collection; nesting is limited to 5 levels and cannot create a cycle. minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.payload
Argument | Required | Type | Details |
| Yes | ['string', 'null'] | Parent collection ID to move this collection under, or null to move it to the top level. Must be a manual collection; nesting is limited to 5 levels and cannot create a cycle. minLength: |
list_asset_collection_assetsBrowse assets in a collection for the authenticated user's fal Assets library.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| No; body/guard requirements still apply | string | Text query for hybrid semantic search |
| No; body/guard requirements still apply | string | fal-hosted image URL to use for semantic image search format: |
| No; body/guard requirements still apply | string | fal-hosted video URL to use for semantic video search format: |
| No; body/guard requirements still apply | ['array', 'null'] | Filter by one or more media types default: |
| No; body/guard requirements still apply | ['array', 'null'] | Filter by one or more indexed sources default: |
| No; body/guard requirements still apply | string | Asset library section to browse enum: |
| No; body/guard requirements still apply | ['array', 'null'] | Character identifiers to use as @mention semantic filters default: |
| No; body/guard requirements still apply | ['array', 'null'] | Tag IDs to filter by default: |
| No; body/guard requirements still apply | string | Whether tag filters match any tag or all tags enum: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
input.media_type
input.media_type[]
Asset media type
input.source
input.source[]
Indexed asset source
input.character_identifier
input.character_identifier[]
Native JSON value; inspect the full schema for validation.
input.tag_id
input.tag_id[]
Native JSON value; inspect the full schema for validation.
add_asset_to_collectionAdd an asset to a manual or character collection. Provide a request ID or vector ID; unresolved references are materialized before local collection state is added. For character collections, the asset is added by applying the character tag.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
remove_asset_from_collectionRemove an asset from a manual or character collection by request ID or vector ID.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
list_asset_charactersList asset characters for the authenticated user's fal Assets library.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | integer | Maximum number of collections to return minimum: |
| No; body/guard requirements still apply | ['integer', 'null'] | Number of collections to skip minimum: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
create_asset_characterCreate an asset character for the authenticated user's fal Assets library. Prefer vector IDs or request IDs in reference_images for existing fal-generated assets; use fal-hosted image URLs only for standalone images. Unresolved ID references are materialized before character state is added.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Character display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional @mention identifier for the character maxLength: |
| No; body/guard requirements still apply | string | Text description used for character semantic matching minLength: |
| No; body/guard requirements still apply | array | Reference images for the character. Prefer vector IDs or request IDs for existing fal-generated assets. Use fal-hosted image URLs only for standalone images. minItems: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the character format: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.reference_images
input.reference_images[]
Native JSON value; inspect the full schema for validation.
input.payload
Argument | Required | Type | Details |
| Yes | string | Character display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional @mention identifier for the character maxLength: |
| Yes | string | Text description used for character semantic matching minLength: |
| Yes | array | Reference images for the character. Prefer vector IDs or request IDs for existing fal-generated assets. Use fal-hosted image URLs only for standalone images. minItems: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the character format: |
input.payload.reference_images
input.payload.reference_images[]
Native JSON value; inspect the full schema for validation.
update_asset_characterUpdate an asset character for the authenticated user's fal Assets library. Prefer vector IDs or request IDs in reference_images for existing fal-generated assets; use fal-hosted image URLs only for standalone images. Unresolved ID references are materialized before character state is added.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Character collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Character display name minLength: |
| No; body/guard requirements still apply | string | Text description used for character semantic matching minLength: |
| No; body/guard requirements still apply | array | Reference images for the character. Prefer vector IDs or request IDs for existing fal-generated assets. Use fal-hosted image URLs only for standalone images. minItems: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the character format: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.reference_images
input.reference_images[]
Native JSON value; inspect the full schema for validation.
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Character display name minLength: |
| No; body/guard requirements still apply | string | Text description used for character semantic matching minLength: |
| No; body/guard requirements still apply | array | Reference images for the character. Prefer vector IDs or request IDs for existing fal-generated assets. Use fal-hosted image URLs only for standalone images. minItems: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the character format: |
input.payload.reference_images
input.payload.reference_images[]
Native JSON value; inspect the full schema for validation.
get_asset_characterGet asset character for the authenticated user's fal Assets library.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | string | Character collection ID minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
delete_asset_characterDelete asset character for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Character collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
favorite_asset_characterFavorite an asset character for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Character collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
unfavorite_asset_characterUnfavorite an asset character for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Character collection ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
list_asset_tagsList asset tags for the authenticated user's fal Assets library.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
create_asset_tagCreate asset tag for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Tag name minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.payload
Argument | Required | Type | Details |
| Yes | string | Tag name minLength: |
set_asset_tags_for_assetSet tags for an asset. Provide a request ID or vector ID; unresolved references are materialized before tag state is added.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | array | Full replacement set of tag IDs |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.tag_ids
input.tag_ids[]
Native JSON value; inspect the full schema for validation.
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| Yes | array | Full replacement set of tag IDs |
input.payload.tag_ids
input.payload.tag_ids[]
Native JSON value; inspect the full schema for validation.
update_asset_tagUpdate asset tag for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Tag ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Tag name minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Tag name minLength: |
delete_asset_tagDelete asset tag for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Tag ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
upload_assetUpload asset for the authenticated user's fal Assets library.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | fal-hosted media URL to ingest into the asset library format: |
| No; body/guard requirements still apply | string | Media type for the uploaded asset enum: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional caller-provided caption or description to index with the uploaded asset minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional manual collection ID to add the uploaded asset to |
| No; body/guard requirements still apply | boolean | Whether to favorite the uploaded asset immediately default: |
| No; body/guard requirements still apply | array | Tag IDs to assign to the uploaded asset default: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.tag_ids
input.tag_ids[]
Native JSON value; inspect the full schema for validation.
input.payload
Argument | Required | Type | Details |
| Yes | string | fal-hosted media URL to ingest into the asset library format: |
| Yes | string | Media type for the uploaded asset enum: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional caller-provided caption or description to index with the uploaded asset minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional manual collection ID to add the uploaded asset to |
| No; body/guard requirements still apply | boolean | Whether to favorite the uploaded asset immediately default: |
| No; body/guard requirements still apply | array | Tag IDs to assign to the uploaded asset default: |
input.payload.tag_ids
input.payload.tag_ids[]
Native JSON value; inspect the full schema for validation.
get_assetGet an asset document by vector ID from the authenticated user's fal Assets library. The vector may exist only in Turbopuffer; in that case the response returns the Turbopuffer document with empty local state.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | string | Vector ID minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
get_asset_lineageGet the derivation lineage of an asset by asset ID: the inputs it was generated from, the generation requests along the way, and any referenced characters, traversed recursively up to depth levels. Deleted or expired ancestors stay in the graph flagged as tombstones; inputs that were never captured appear as external inputs.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | string | Asset ID minLength: |
| No; body/guard requirements still apply | integer | Maximum traversal depth (levels of derivation edges) minimum: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
favorite_assetFavorite an asset. Provide a request ID or vector ID; unresolved references are materialized before favorite state is added.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
unfavorite_assetUnfavorite an asset by request ID or vector ID.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
list_asset_tags_for_assetList tags for an asset by vector ID. Vectors that have not been saved as assets return an empty tag list.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | string | Vector ID minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
assign_asset_tagAssign a tag to an asset. Provide a request ID or vector ID; unresolved references are materialized before tag state is added.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Tag ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
unassign_asset_tagUnassign a tag from an asset by request ID or vector ID.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Tag ID minLength: |
| No; body/guard requirements still apply | string | Optional idempotency key for safe request retries |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
get_storage_file_aclReturns the Access Control List currently applied to a fal CDN file. The ACL consists of a default decision (allow, forbid, or hide) plus optional per-user rules that override the default. Rule users are returned as nicknames where possible. Authentication: Required. The API key must have the assets:read permission.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | string | Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b//). Must not contain query parameters. format: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
set_storage_file_aclReplaces the Access Control List of a fal CDN file. The ACL consists of a default decision (allow, forbid, or hide) plus optional per-user rules that override the default. Rule users may be specified by nickname or user ID. Setting default to allow with no rules makes the file public; forbid or hide restricts it to the rules you provide. Rules referencing users that do not exist are dropped. The response reflects the ACL actually applied, so verify it contains the rules you sent. Authentication: Required. The API key must have the assets:write permission.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b//). Must not contain query parameters. format: |
| No; body/guard requirements still apply | string | Fallback decision when no user-specific rule matches enum: |
| No; body/guard requirements still apply | array | User-specific overrides to the default decision default: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.rules
input.rules[]
Argument | Required | Type | Details |
| Yes | string | User nickname or user ID the rule applies to minLength: |
| Yes | string | Access decision applied to this user enum: |
input.payload
Argument | Required | Type | Details |
| Yes | string | Fallback decision when no user-specific rule matches enum: |
| No; body/guard requirements still apply | array | User-specific overrides to the default decision default: |
input.payload.rules
input.payload.rules[]
Argument | Required | Type | Details |
| Yes | string | User nickname or user ID the rule applies to minLength: |
| Yes | string | Access decision applied to this user enum: |
sign_storage_file_urlCreates a signed URL that grants temporary access to a fal CDN file, regardless of its ACL. Useful for sharing access-restricted files. The signature is valid for expiration_seconds (up to 7 days). Authentication: Required. The API key must have the assets:read permission.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b//). Must not contain query parameters. format: |
| No; body/guard requirements still apply | integer | How long the signed URL stays valid, in seconds (max 7 days) minimum: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
| Yes | string | Required absolute new owner-private file; signed credential URL is never echoed. minLength: |
input.payload
Argument | Required | Type | Details |
| Yes | integer | How long the signed URL stays valid, in seconds (max 7 days) minimum: |
get_storage_settingsReturns the account-level storage lifecycle settings applied to newly uploaded fal CDN files: - expiration_duration_seconds: how long files live before being automatically deleted (null disables auto-expiration). - initial_acl: the default ACL applied to new uploads (null means the system default, which is public). Both fields are null when the account has never saved settings. Authentication: Required. The API key must have the account:settings:read permission.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
update_storage_settingsReplaces the account-level storage lifecycle settings applied to newly uploaded fal CDN files. Omitted or null fields are cleared (reset to the system default), so always send the full desired configuration. ACL rules referencing users that do not exist are dropped. The response reflects the settings actually saved, so verify it contains the rules you sent. These are the same settings that the per-request X-Fal-Object-Lifecycle-Preference header overrides on individual requests. Authentication: Required. The API key must have the account:settings:write permission.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Seconds after which newly uploaded files automatically expire and are deleted. Null disables auto-expiration. minimum: |
| No; body/guard requirements still apply | ['object', 'null'] | Default ACL applied to newly uploaded files. Null uses the system default (public). |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. |
| No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: |
input.initial_acl
Argument | Required | Type | Details |
| Yes | string | Fallback decision when no user-specific rule matches enum: |
| No; body/guard requirements still apply | array | User-specific overrides to the default decision default: |
input.initial_acl.rules
input.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | User nickname or user ID the rule applies to minLength: |
| Yes | string | Access decision applied to this user enum: |
input.payload
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Seconds after which newly uploaded files automatically expire and are deleted. Null disables auto-expiration. minimum: |
| No; body/guard requirements still apply | ['object', 'null'] | Default ACL applied to newly uploaded files. Null uses the system default (public). |
input.payload.initial_acl
Argument | Required | Type | Details |
| Yes | string | Fallback decision when no user-specific rule matches enum: |
| No; body/guard requirements still apply | array | User-specific overrides to the default decision default: |
input.payload.initial_acl.rules
input.payload.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | User nickname or user ID the rule applies to minLength: |
| Yes | string | Access decision applied to this user enum: |
get_account_billingReturns billing information for the authenticated account. Use the expand parameter to include additional details. Expandable Fields: - credits : Current credit balance and currency Common Use Cases: - Monitor available credit balance programmatically - Display balance in custom dashboards
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | JSON | Data to include in the response. Use 'credits' to include current credit balance. |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
input.expand
input.expand anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.expand anyOf branch 2
input.expand.anyOf2[]
Native JSON value; inspect the full schema for validation.
get_organization_teamsReturns the list of teams in your organization with their details. > Availability: This endpoint is available to enterprise customers with organizations enabled. Contact your account team or support@fal.ai to request access. Must be called with an admin API key on the organization's root team. Key Features: - List all teams within the organization - Identify the organization's root team via is_org_root - View team usernames and display names See fal.ai docs for more details.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
get_organization_usageReturns paginated usage records across all teams and product lines in your organization, with each record attributed to a specific team via the username field and a product line via the product field. Covers all three fal product lines: - model_apis : model API endpoint calls (e.g. fal-ai/flux/dev) - serverless : fal Serverless SDK billing - compute : fal Compute (raw instance time) > Availability: This endpoint is available to enterprise customers with organizations enabled. Contact your account team or support@fal.ai to request access. Must be called with an admin API key on the organization's root team. Key Features: - Organization-wide usage data across all teams and products - Filter by team(s) (team_username), product line (product), endpoint, API key (api_key_id), date range, and auth method - Per-team and per-product attribution on every usage record - Paginated time series and aggregate summary views See fal.ai docs for more details.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: |
| No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. |
| No; body/guard requirements still apply | JSON | Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago. |
| No; body/guard requirements still apply | JSON | 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. |
| No; body/guard requirements still apply | string | Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed. default: |
| No; body/guard requirements still apply | string | 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). enum: |
| No; body/guard requirements still apply | string | 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. enum: |
| No; body/guard requirements still apply | JSON | 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 |
| No; body/guard requirements still apply | JSON | 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 |
| No; body/guard requirements still apply | JSON | Filter by one or more team usernames within the organization. Accepts a comma-separated list or repeated parameter. If not provided, returns usage across all teams. |
| No; body/guard requirements still apply | JSON | Restrict results to one or more product lines. Accepts a comma-separated list or repeated parameter. Defaults to all three (model_apis, serverless, compute). |
| No; body/guard requirements still apply | JSON | Data to include in the response. Use 'time_series' for time-bucketed data, 'summary' for aggregate statistics, 'auth_method' for a resolved authentication method label, and 'auth_method_structured' for a machine-readable auth method object (detail, api_key_id, login_username). At least one of 'time_series' or 'summary' is required. default: |
| No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |
input.start
input.start anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.start anyOf branch 2
Native JSON value; inspect the full schema for validation.
input.end
input.end anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.end anyOf branch 2
Native JSON value; inspect the full schema for validation.
input.endpoint_id
input.endpoint_id anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.endpoint_id anyOf branch 2
input.endpoint_id.anyOf2[]
Native JSON value; inspect the full schema for validation.
input.api_key_id
input.api_key_id anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.api_key_id anyOf branch 2
input.api_key_id.anyOf2[]
Native JSON value; inspect the full schema for validation.
input.team_username
input.team_username anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.team_username anyOf branch 2
input.team_username.anyOf2[]
Native JSON value; inspect the full schema for validation.
input.product
input.product anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.product anyOf branch 2
input.product.anyOf2[]
Native JSON value; inspect the full schema for validation.
input.expand
input.expand anyOf branch 1
Native JSON value; inspect the full schema for validation.
input.expand anyOf branch 2
input.expand.anyOf2[]
Native JSON value; inspect the full schema for validation.
get_model_infoExact current catalog lookup with OpenAPI expansion. No generation or inferred model defaults. Schema may be unavailable; inspect actual native fields.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
run_modelConfirmed paid model request after current native input-schema validation. Exact model_id/input required; image/video commands do not invent fields or choose a default. Queue submissions return receipt only; synchronous timeout may leave an unknown paid outcome. No retry or polling.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | object | Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters. |
| No; body/guard requirements still apply | object | Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider. |
| No; body/guard requirements still apply | boolean | Local default false sends X-Fal-Store-IO:0. true allows provider JSON payload storage; CDN media retention/ACL is separate. default: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
input.lifecycle
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Native field; use the reviewed provider reference. minimum: |
| No; body/guard requirements still apply | object | Native field; use the reviewed provider reference. |
input.lifecycle.initial_acl
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. enum: |
| No; body/guard requirements still apply | array | Native field; use the reviewed provider reference. maxItems: |
input.lifecycle.initial_acl.rules
input.lifecycle.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. minLength: |
| Yes | string | Native field; use the reviewed provider reference. enum: |
submit_jobConfirmed paid model request after current native input-schema validation. Exact model_id/input required; image/video commands do not invent fields or choose a default. Queue submissions return receipt only; synchronous timeout may leave an unknown paid outcome. No retry or polling.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | object | Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters. |
| No; body/guard requirements still apply | object | Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider. |
| No; body/guard requirements still apply | boolean | Local default false sends X-Fal-Store-IO:0. true allows provider JSON payload storage; CDN media retention/ACL is separate. default: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
input.lifecycle
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Native field; use the reviewed provider reference. minimum: |
| No; body/guard requirements still apply | object | Native field; use the reviewed provider reference. |
input.lifecycle.initial_acl
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. enum: |
| No; body/guard requirements still apply | array | Native field; use the reviewed provider reference. maxItems: |
input.lifecycle.initial_acl.rules
input.lifecycle.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. minLength: |
| Yes | string | Native field; use the reviewed provider reference. enum: |
generate_imageConfirmed paid model request after current native input-schema validation. Exact model_id/input required; image/video commands do not invent fields or choose a default. Queue submissions return receipt only; synchronous timeout may leave an unknown paid outcome. No retry or polling.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | object | Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters. |
| No; body/guard requirements still apply | object | Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider. |
| No; body/guard requirements still apply | boolean | Local default false sends X-Fal-Store-IO:0. true allows provider JSON payload storage; CDN media retention/ACL is separate. default: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
input.lifecycle
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Native field; use the reviewed provider reference. minimum: |
| No; body/guard requirements still apply | object | Native field; use the reviewed provider reference. |
input.lifecycle.initial_acl
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. enum: |
| No; body/guard requirements still apply | array | Native field; use the reviewed provider reference. maxItems: |
input.lifecycle.initial_acl.rules
input.lifecycle.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. minLength: |
| Yes | string | Native field; use the reviewed provider reference. enum: |
generate_videoConfirmed paid model request after current native input-schema validation. Exact model_id/input required; image/video commands do not invent fields or choose a default. Queue submissions return receipt only; synchronous timeout may leave an unknown paid outcome. No retry or polling.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | object | Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters. |
| No; body/guard requirements still apply | object | Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider. |
| No; body/guard requirements still apply | boolean | Local default false sends X-Fal-Store-IO:0. true allows provider JSON payload storage; CDN media retention/ACL is separate. default: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
input.lifecycle
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Native field; use the reviewed provider reference. minimum: |
| No; body/guard requirements still apply | object | Native field; use the reviewed provider reference. |
input.lifecycle.initial_acl
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. enum: |
| No; body/guard requirements still apply | array | Native field; use the reviewed provider reference. maxItems: |
input.lifecycle.initial_acl.rules
input.lifecycle.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. minLength: |
| Yes | string | Native field; use the reviewed provider reference. enum: |
get_job_statusOne read using the SDK-compatible owner/app root, not the full model subpath. No auto-polling, paid re-submission or arbitrary status URL.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | string | Exact queue receipt ID; status/result/cancel use its owner/app root, without inference subpaths. pattern: |
| No; body/guard requirements still apply | boolean | Include native provider logs only when requested. default: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
get_job_resultOne result read using the receipt/model root. No wait loop, media download, re-submission or auto-upload. Signed credential URLs are redacted; ordinary output media URLs remain account data.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | string | Exact queue receipt ID; status/result/cancel use its owner/app root, without inference subpaths. pattern: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
cancel_jobConfirmed native cancellation request. Cancellation receipt is not proof processing stopped or credits were refunded; current provider state controls eligibility. No retry.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | string | Exact queue receipt ID; status/result/cancel use its owner/app root, without inference subpaths. pattern: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
upload_fileConfirmed selected absolute regular non-symlink local file, 1 byte–20 MiB. Uses pinned SDK upload-initiation protocol then a credential-free HTTPS fal.media PUT with redirects refused. No remote URL ingestion, base64 model output, multipart retries or automatic generation.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | string | Absolute selected local media file, regular/non-symlink, 1 byte–20 MiB. minLength: |
| Yes | string | Plain MIME type matching the selected media. pattern: |
| No; body/guard requirements still apply | object | Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider. |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
input.lifecycle
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Native field; use the reviewed provider reference. minimum: |
| No; body/guard requirements still apply | object | Native field; use the reviewed provider reference. |
input.lifecycle.initial_acl
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. enum: |
| No; body/guard requirements still apply | array | Native field; use the reviewed provider reference. maxItems: |
input.lifecycle.initial_acl.rules
input.lifecycle.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. minLength: |
| Yes | string | Native field; use the reviewed provider reference. enum: |
list_accountsLocal labels/default/auth method only. No keys, token paths, real provider identities or network request.
Policy: Read/helper; no explicit mutation approval.
Native JSON value; inspect the full schema for validation.
get_operation_schemaLocal current native method/path/query/header/body schema and exact provenance. No credential or provider request.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. enum: |
preview_generation_batchRead-only current schema validation and native unit-pricing lookup for all requested async jobs. Hash binds ordered exact inputs/lifecycle/store-IO/profile label/current schemas/unit quotes. Unit pricing is not final cost or a spending cap. No generation, file write or key ownership validation.
Policy: Read/helper; no explicit mutation approval.
Argument | Required | Type | Details |
| Yes | array | One to ten ordered async generation payloads. CLI repeats --tasks individual JSON objects. One job can produce several outputs; this is not a cost or output-count budget. minItems: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
input.tasks
input.tasks[]
Argument | Required | Type | Details |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | object | Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters. |
| No; body/guard requirements still apply | object | Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider. |
| No; body/guard requirements still apply | boolean | Local default false sends X-Fal-Store-IO:0. true allows provider JSON payload storage; CDN media retention/ACL is separate. default: |
input.tasks[].lifecycle
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Native field; use the reviewed provider reference. minimum: |
| No; body/guard requirements still apply | object | Native field; use the reviewed provider reference. |
input.tasks[].lifecycle.initial_acl
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. enum: |
| No; body/guard requirements still apply | array | Native field; use the reviewed provider reference. maxItems: |
input.tasks[].lifecycle.initial_acl.rules
input.tasks[].lifecycle.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. minLength: |
| Yes | string | Native field; use the reviewed provider reference. enum: |
submit_generation_batchConfirmed one-to-ten async jobs. Refetch all current schemas/unit quotes and validate all before first paid submission; refuse changed hash. Submit sequentially, stop on first failure, report known request IDs/failed and unattempted indices. No polling, retries, rollback, continuation or budget guarantee.
Policy: Confirmed operation; read-only hides and directly refuses it.
Argument | Required | Type | Details |
| Yes | array | One to ten ordered async generation payloads. CLI repeats --tasks individual JSON objects. One job can produce several outputs; this is not a cost or output-count budget. minItems: |
| No; body/guard requirements still apply | string | Exact configured isolated API-key profile label. |
| No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |
| Yes | string | Native field; use the reviewed provider reference. pattern: |
input.tasks
input.tasks[]
Argument | Required | Type | Details |
| Yes | string | Exact current catalog endpoint ID. Never guess model names or parameter mappings. minLength: |
| Yes | object | Exact native model inputs. Fetched current model JSON schema validates these before a paid request; no guessed prompt/image/duration adapters. |
| No; body/guard requirements still apply | object | Native CDN expiry/ACL preference. Omit to use account defaults. null expiration means no expiry; default CDN access may be public. Unknown nicknames may be dropped by provider. |
| No; body/guard requirements still apply | boolean | Local default false sends X-Fal-Store-IO:0. true allows provider JSON payload storage; CDN media retention/ACL is separate. default: |
input.tasks[].lifecycle
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Native field; use the reviewed provider reference. minimum: |
| No; body/guard requirements still apply | object | Native field; use the reviewed provider reference. |
input.tasks[].lifecycle.initial_acl
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. enum: |
| No; body/guard requirements still apply | array | Native field; use the reviewed provider reference. maxItems: |
input.tasks[].lifecycle.initial_acl.rules
input.tasks[].lifecycle.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | Native field; use the reviewed provider reference. minLength: |
| Yes | string | Native field; use the reviewed provider reference. enum: |
search_models: GET /modelsUnified endpoint for discovering model endpoints. Supports three usage modes: 1. List Mode (no parameters): Paginated list of all available model endpoints with minimal metadata. 2. Find Mode (endpoint_id parameter): Retrieve specific model endpoint(s) by ID. Supports single or multiple IDs. 3. Search Mode (search parameters): Filter models by free-text query, category, or status. Expansion: Use expand to include additional data in each model object: - openapi-3.0 : full OpenAPI 3.0 schema in the openapi field - enterprise_status : enterprise readiness status (ready or pending) in the enterprise_status field Examples of endpoint_id values: - fal-ai/flux/dev - fal-ai/wan/v2.2-a14b/text-to-video - fal-ai/minimax/video-01/image-to-video - fal-ai/hunyuan3d-v21 See fal.ai Model APIs for more details. Authentication: Optional. Providing an API key grants higher rate limits. Common Use Cases: - Browse available models for integration - Retrieve metadata for specific endpoints - Search for models by category or keywords - Get OpenAPI schemas for code generation - Build model selection interfaces
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "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"} |
query |
| False | {"type": "string", "description": "Free-text search query to filter models by name, description, or category"} |
query |
| False | {"type": "string", "description": "Filter by category (e.g., 'text-to-image', 'image-to-video', 'training')"} |
query |
| False | {"type": "string", "enum": ["active", "deprecated"], "description": "Filter models by status - omit to include all statuses"} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "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)"} |
get_pricing: GET /models/pricingReturns 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. Authentication: Required. Users must provide a valid API key. Custom pricing or discounts may be applied based on account status. Common Use Cases: - Display pricing in user interfaces - Compare pricing across different models - Build cost estimation tools - Check current billing rates See fal.ai pricing for more details.
Location | Parameter | Required | Native shape |
query |
| True | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "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"} |
estimate_pricing: POST /models/pricing/estimateComputes cost estimates using one of two methods: 1. Historical API Price (historical_api_price): - Based on historical pricing per API call from past usage patterns - Takes call_quantity (number of API calls) per endpoint - Useful for estimating based on actual historical usage patterns - Example: "How much will 100 calls to flux/dev cost?" 2. Unit Price (unit_price): - Based on unit price × expected billing units from pricing service - Takes unit_quantity (number of billing units like images/videos) per endpoint - Useful when you know the expected output quantity - Example: "How much will 50 images from flux/dev cost?" Authentication: Required. Users must provide a valid API key. Custom pricing or discounts may be applied based on account status. Common Use Cases: - Pre-calculate costs for batch operations - Display cost estimates in user interfaces - Budget planning and cost optimization See fal.ai pricing for more details.
Location | Parameter | Required | Native shape |
Native request | No path/query/header arguments | No | See required body below |
Native body required: False. Complete body sources cannot mix.
body oneOf branch 1
Argument | Required | Type | Details |
| Yes | string | Estimate type: historical API pricing based on past usage patterns enum: |
| Yes | object | Map of endpoint IDs to call quantities |
body.oneOf1.endpoints
body.oneOf1.endpoints.{key}
Argument | Required | Type | Details |
| Yes | integer | Number of API calls to estimate (regardless of units per call) minimum: |
body oneOf branch 2
Argument | Required | Type | Details |
| Yes | string | Estimate type: unit price calculation based on billing units enum: |
| Yes | object | Map of endpoint IDs to unit quantities |
body.oneOf2.endpoints
body.oneOf2.endpoints.{key}
Argument | Required | Type | Details |
| Yes | number | Number of billing units expected (e.g., number of images, videos, etc.) minimum: |
get_usage: GET /models/usageReturns 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 − cost_discount). Key Features: - Usage data for all endpoints or filtered by specific endpoint(s) - Flexible date range filtering - User-specific usage tracking - Detailed usage line items with unit quantity, price, and discount breakdown - Paginated results for large datasets Common Use Cases: - Generate usage reports for all endpoints or specific models - Track usage patterns - Monitor endpoint usage across different auth methods - Build usage dashboards and visualizations See fal.ai docs for more details.
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| False | {"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago."} |
query |
| False | {"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "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."} |
query |
| False | {"type": "string", "default": "UTC", "description": "Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed."} |
query |
| False | {"type": "string", "enum": ["minute", "hour", "day", "week", "month"], "description": "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)."} |
query |
| False | {"type": "string", "enum": ["true", "false"], "default": "true", "description": "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."} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "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"} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "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"} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "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"} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "default": ["time_series"], "description": "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."} |
get_analytics: GET /models/analyticsTime-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. Metric Selection: You must specify which metrics to include using the expand query parameter. Only requested metrics will be populated in the response, allowing you to optimize query performance and data transfer. Available Metrics: The expand parameter accepts these values, grouped by category: Volume - request_count: Total number of requests in the time bucket - success_count: Successful requests (2xx responses) - user_error_count: User errors (4xx responses) - error_count: Server errors (5xx responses) Error type breakdown - startup_error_count: Startup errors (startup timeout, scheduling failure) - connection_error_count: Connection errors (timeout, disconnected, refused) - timeout_error_count: Request timeout errors - runtime_error_count: Runtime errors (internal error, server error) Queue / prepare latency - p50_prepare_duration, p75_prepare_duration, p90_prepare_duration, p95_prepare_duration, p99_prepare_duration: Time from request submission until execution starts Request execution latency - p25_duration, p50_duration, p75_duration, p90_duration, p95_duration, p99_duration: Time spent processing the request Cold boot - cold_boot_count: Requests with cold boot (startup > 1s) - p50_cold_boot_duration, p75_cold_boot_duration, p90_cold_boot_duration: Cold boot duration percentiles Billing - total_billable_duration: Aggregate billed execution time Key Features: - Selective metric inclusion via expand parameter - Performance metrics (latency percentiles, duration stats) - Reliability metrics (success/error rates, request counts) - Error type breakdown (startup, connection, timeout, runtime) - Cold boot metrics (count, latency percentiles) - Billing duration tracking - Time-bucketed data for trend analysis - Single or multi-model analytics - Flexible date range and timeframe options Common Use Cases: - Monitor model performance and reliability - Generate performance dashboards - Analyze latency trends and patterns - Track error rates and success metrics See Queue API docs for more details.
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| False | {"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago."} |
query |
| False | {"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "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."} |
query |
| False | {"type": "string", "default": "UTC", "description": "Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed."} |
query |
| False | {"type": "string", "enum": ["minute", "hour", "day", "week", "month"], "description": "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)."} |
query |
| False | {"type": "string", "enum": ["true", "false"], "default": "true", "description": "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."} |
query |
| True | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "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"} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "default": ["time_series", "request_count"], "description": "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."} |
get_billing_events: GET /models/billing-eventsReturns paginated individual billing event records with filters for endpoint and date range. Each record includes the request ID, timestamp, endpoint, output units billed, and a cost breakdown in USD (cost_subtotal, cost_discount, cost_total; cost_estimate_nano_usd carries cost_total in nano USD). Key Features: - Individual billing event records for each API request - Per-request cost breakdown before and after discounts - Flexible date range filtering - Optional endpoint filtering - Cursor-based pagination for efficient large dataset queries - Limited to 10000 records per page for performance - Date range capped at 90 days per request Common Use Cases: - Audit individual billing events - Track request patterns and volumes - Debug specific requests by ID - Monitor billing unit consumption per request See fal.ai docs for more details.
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| False | {"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago."} |
query |
| False | {"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "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."} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "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"} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "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"} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "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"} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "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"} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "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)."} |
delete_request_payloads: DELETE /models/requests/{request_id}/payloadsDeletes the IO payloads and associated CDN output files for a specific request. Important: - Only output CDN files are deleted (input files may be used by other requests) - This action is irreversible - Requires authentication with an admin API key What gets deleted: - Request input/output payload data - CDN-hosted output files (images, videos, etc.) What is NOT deleted: - Input CDN files (may be referenced by other requests) Response: - Returns deletion status for each CDN file - Each result includes the file link and any error that occurred Idempotency: - Optional Idempotency-Key header prevents duplicate deletions on retries - Responses cached for 10 minutes per unique key See fal.ai docs for more details about request payloads.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "format": "uuid", "description": "Unique identifier for the request (UUID format)"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
list_requests_by_endpoint: GET /models/requests/by-endpointLists requests for one or more endpoints (same endpoint_id style as usage/explore: comma-separated or repeated query params, up to 50 IDs). Authentication: Requires API key (user or enterprise). Filters: - Time range via start / end. If start is omitted, defaults to the last 24 hours : unless request_id is provided, in which case the default start bound is widened to 90 days. - Status (success, error, user_error) - Request ID - Pagination via cursor/limit (limit defaults to 50, max 100) Sorting: - By end time (default) or duration Expansions: - Include payloads by adding expand=payloads
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Number of items to return per page (max 100)"} |
query |
| False | {"type": "string", "description": "Pagination cursor encoding the page number"} |
query |
| True | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "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"} |
query |
| False | {"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago."} |
query |
| False | {"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "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."} |
query |
| False | {"type": "string", "enum": ["success", "error", "user_error"], "description": "Filter by request status"} |
query |
| False | {"type": "string", "format": "uuid", "description": "Filter by specific request ID"} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Fields to expand in the response. Use payloads to include input and output payloads."} |
query |
| False | {"type": "string", "enum": ["ended_at", "duration"], "default": "ended_at", "description": "Sort results by end time or duration"} |
search_requests: GET /models/requests/searchSearch, filter, and browse your request history. Supports three modes: 1. Semantic Search (query, image_url, or video_url parameter): Find visually or conceptually similar results using AI embeddings. Provide a text query for text-to-image search, an image URL for image-to-image similarity search, or a video URL for video-to-image similarity search. 2. Filtered Browse (no query, image_url, or video_url): Browse request history with hard filters. Returns results ordered by creation date (newest first). 3. Semantic + Filters (search params AND filter params): Combine semantic search with hard filters. Filters narrow the candidate set before ranking by similarity. Filter Options: - endpoint_id: Filter by one or more fal endpoints (comma-separated or repeated, up to 50 IDs) - exclude_api_requests / only_api_requests: Filter by request source Examples: - Semantic text search: ?query=sunset+landscape - Image similarity: ?image_url=https://...&min_similarity=0.5 - Filtered search: ?query=portrait&endpoint_id=fal-ai/flux/dev - Browse across multiple endpoints: ?endpoint_id=fal-ai/flux/dev,fal-ai/flux/schnell
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| False | {"type": "string", "description": "Text search query for semantic search. Mutually exclusive with image_url and video_url."} |
query |
| False | {"type": "string", "description": "Image URL for similarity search. Mutually exclusive with query and video_url."} |
query |
| False | {"type": "string", "description": "Video URL for similarity search. Mutually exclusive with query and image_url."} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by one or more fal endpoints to scope request history. Accepts comma-separated or repeated values (1-50 IDs)."} |
query |
| False | {"type": "string", "description": "Deprecated: use |
query |
| False | {"type": "boolean", "description": "Exclude requests made via API keys (only show playground/UI requests). Mutually exclusive with only_api_requests."} |
query |
| False | {"type": "boolean", "description": "Only include requests made via API keys. Mutually exclusive with exclude_api_requests."} |
query |
| False | {"type": ["number", "null"], "minimum": 0, "maximum": 1, "description": "Minimum similarity score (0-1) for semantic search results. Only applies when query or image_url is provided."} |
list_workflows: GET /workflowsList workflows for the authenticated user with optional search and filtering. Features: - Paginated results with cursor-based pagination - Search by workflow name or title - Filter by model endpoints used in the workflow Authentication: Required. Returns only workflows owned by the authenticated user. Common Use Cases: - Display user's workflow library - Search for specific workflows - Find workflows using particular models
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| False | {"type": "string", "description": "Search by workflow name or title"} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by model endpoint IDs used in the workflow. Can be a single value or comma-separated values."} |
create_workflow: POST /workflowsCreate a new workflow owned by the authenticated user. Authentication: Required. Common Use Cases: - Save a newly built workflow - Programmatically provision workflows Note: Workflow names must be unique within your namespace. Creating a workflow with a name you already use returns a 400 validation error.
Location | Parameter | Required | Native shape |
Native request | No path/query/header arguments | No | See required body below |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| Yes | string | Unique workflow name/slug within the user's namespace maxLength: |
| Yes | string | Human-readable workflow title minLength: |
| Yes | object | The workflow definition/configuration object |
| No; body/guard requirements still apply | boolean | Whether the workflow is publicly visible default: |
body.contents
Argument | Required | Type | Details |
| Yes | string | Internal name of the workflow definition |
| Yes | string | Workflow definition format version |
| Yes | object | Workflow nodes keyed by node id |
| Yes | object | Output field mappings keyed by output name |
| Yes | object | Input/output schema for the workflow |
| No; body/guard requirements still apply | object | Optional workflow metadata |
body.contents.nodes
body.contents.nodes.{key}
body.contents.nodes.{key}.{key}
Native JSON value; inspect the full schema for validation.
body.contents.output
body.contents.output.{key}
Native JSON value; inspect the full schema for validation.
body.contents.schema
Argument | Required | Type | Details |
| Yes | object | Input fields schema |
| Yes | object | Output fields schema |
body.contents.schema.input
body.contents.schema.input.{key}
Native JSON value; inspect the full schema for validation.
body.contents.schema.output
body.contents.schema.output.{key}
Native JSON value; inspect the full schema for validation.
body.contents.metadata
body.contents.metadata.{key}
Native JSON value; inspect the full schema for validation.
get_workflow: GET /workflows/{username}/{workflow_name}Get detailed information about a specific workflow, including its full contents/definition. Authentication: Required. Common Use Cases: - Load a workflow for editing - View workflow configuration - Export workflow definition
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$", "description": "The username of the workflow owner"} |
path |
| True | {"type": "string", "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$", "description": "The workflow name/slug"} |
list_assets: GET /assetsBrowse and semantically search fal Assets across all media, uploads, favorites, collections, tags, and character references.
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| False | {"type": "string", "description": "Text query for hybrid semantic search"} |
query |
| False | {"type": "string", "format": "uri", "description": "fal-hosted image URL to use for semantic image search"} |
query |
| False | {"type": "string", "format": "uri", "description": "fal-hosted video URL to use for semantic video search"} |
query |
| False | {"type": ["array", "null"], "items": {"type": "string", "enum": ["image", "video", "audio", "3d"], "description": "Asset media type"}, "default": [], "description": "Filter by one or more media types"} |
query |
| False | {"type": ["array", "null"], "items": {"type": "string", "enum": ["upload", "response", "request"], "description": "Indexed asset source"}, "default": [], "description": "Filter by one or more indexed sources"} |
query |
| False | {"type": "string", "enum": ["all-media", "uploads", "favorites", "generated"], "default": "all-media", "description": "Asset library section to browse"} |
query |
| False | {"type": "string", "description": "Collection scope to browse"} |
query |
| False | {"type": ["array", "null"], "items": {"type": "string"}, "default": [], "description": "Character identifiers to use as @mention semantic filters"} |
query |
| False | {"type": ["array", "null"], "items": {"type": "string"}, "default": [], "description": "Tag IDs to filter by"} |
query |
| False | {"type": "string", "enum": ["any", "all"], "default": "any", "description": "Whether tag filters match any tag or all tags"} |
list_asset_collections: GET /assets/collectionsList asset collections for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of collections to return"} |
query |
| False | {"type": ["integer", "null"], "minimum": 0, "default": 0, "description": "Number of collections to skip"} |
create_asset_collection: POST /assets/collectionsCreate asset collection for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| Yes | string | Collection display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection description |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection icon |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection color |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the collection format: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional parent collection ID to nest this collection under (manual collections only). Omit or null to create a top-level collection. minLength: |
| No; body/guard requirements still apply | JSON | Assets filter DSL |
get_asset_collection: GET /assets/collections/{collection_id}Get asset collection for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
update_asset_collection: PATCH /assets/collections/{collection_id}Update asset collection for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Collection display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection description |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection icon |
| No; body/guard requirements still apply | ['string', 'null'] | Optional collection color |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the collection format: |
| No; body/guard requirements still apply | JSON | Assets filter DSL |
delete_asset_collection: DELETE /assets/collections/{collection_id}Delete asset collection for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
get_asset_collection_hierarchy: GET /assets/collections/{collection_id}/hierarchyGet the nested subtree rooted at an asset collection, plus its ancestor collections ordered from the top level down to its direct parent.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
favorite_asset_collection: POST /assets/collections/{collection_id}/favoriteFavorite an asset collection for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
unfavorite_asset_collection: POST /assets/collections/{collection_id}/unfavoriteUnfavorite an asset collection for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
move_asset_collection: POST /assets/collections/{collection_id}/moveMove a manual asset collection under another collection, or to the top level. Only manual collections can be moved or act as folders; nesting is limited to 5 levels deep and cannot create a cycle.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| Yes | ['string', 'null'] | Parent collection ID to move this collection under, or null to move it to the top level. Must be a manual collection; nesting is limited to 5 levels and cannot create a cycle. minLength: |
list_asset_collection_assets: GET /assets/collections/{collection_id}/assetsBrowse assets in a collection for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| False | {"type": "string", "description": "Text query for hybrid semantic search"} |
query |
| False | {"type": "string", "format": "uri", "description": "fal-hosted image URL to use for semantic image search"} |
query |
| False | {"type": "string", "format": "uri", "description": "fal-hosted video URL to use for semantic video search"} |
query |
| False | {"type": ["array", "null"], "items": {"type": "string", "enum": ["image", "video", "audio", "3d"], "description": "Asset media type"}, "default": [], "description": "Filter by one or more media types"} |
query |
| False | {"type": ["array", "null"], "items": {"type": "string", "enum": ["upload", "response", "request"], "description": "Indexed asset source"}, "default": [], "description": "Filter by one or more indexed sources"} |
query |
| False | {"type": "string", "enum": ["all-media", "uploads", "favorites", "generated"], "default": "all-media", "description": "Asset library section to browse"} |
query |
| False | {"type": ["array", "null"], "items": {"type": "string"}, "default": [], "description": "Character identifiers to use as @mention semantic filters"} |
query |
| False | {"type": ["array", "null"], "items": {"type": "string"}, "default": [], "description": "Tag IDs to filter by"} |
query |
| False | {"type": "string", "enum": ["any", "all"], "default": "any", "description": "Whether tag filters match any tag or all tags"} |
add_asset_to_collection: POST /assets/collections/{collection_id}/assetsAdd an asset to a manual or character collection. Provide a request ID or vector ID; unresolved references are materialized before local collection state is added. For character collections, the asset is added by applying the character tag.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
remove_asset_from_collection: DELETE /assets/collections/{collection_id}/assetsRemove an asset from a manual or character collection by request ID or vector ID.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
list_asset_characters: GET /assets/charactersList asset characters for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of collections to return"} |
query |
| False | {"type": ["integer", "null"], "minimum": 0, "default": 0, "description": "Number of collections to skip"} |
create_asset_character: POST /assets/charactersCreate an asset character for the authenticated user's fal Assets library. Prefer vector IDs or request IDs in reference_images for existing fal-generated assets; use fal-hosted image URLs only for standalone images. Unresolved ID references are materialized before character state is added.
Location | Parameter | Required | Native shape |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| Yes | string | Character display name minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional @mention identifier for the character maxLength: |
| Yes | string | Text description used for character semantic matching minLength: |
| Yes | array | Reference images for the character. Prefer vector IDs or request IDs for existing fal-generated assets. Use fal-hosted image URLs only for standalone images. minItems: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the character format: |
body.reference_images
body.reference_images[]
Native JSON value; inspect the full schema for validation.
update_asset_character: PATCH /assets/characters/{character_id}Update an asset character for the authenticated user's fal Assets library. Prefer vector IDs or request IDs in reference_images for existing fal-generated assets; use fal-hosted image URLs only for standalone images. Unresolved ID references are materialized before character state is added.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Character collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Character display name minLength: |
| No; body/guard requirements still apply | string | Text description used for character semantic matching minLength: |
| No; body/guard requirements still apply | array | Reference images for the character. Prefer vector IDs or request IDs for existing fal-generated assets. Use fal-hosted image URLs only for standalone images. minItems: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the character format: |
body.reference_images
body.reference_images[]
Native JSON value; inspect the full schema for validation.
get_asset_character: GET /assets/characters/{character_id}Get asset character for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Character collection ID"} |
delete_asset_character: DELETE /assets/characters/{character_id}Delete asset character for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Character collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
favorite_asset_character: POST /assets/characters/{character_id}/favoriteFavorite an asset character for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Character collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
unfavorite_asset_character: POST /assets/characters/{character_id}/unfavoriteUnfavorite an asset character for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Character collection ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
list_asset_tags: GET /assets/tagsList asset tags for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
Native request | No path/query/header arguments | No | See required body below |
create_asset_tag: POST /assets/tagsCreate asset tag for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| Yes | string | Tag name minLength: |
set_asset_tags_for_asset: PUT /assets/tagsSet tags for an asset. Provide a request ID or vector ID; unresolved references are materialized before tag state is added.
Location | Parameter | Required | Native shape |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
| Yes | array | Full replacement set of tag IDs |
body.tag_ids
body.tag_ids[]
Native JSON value; inspect the full schema for validation.
update_asset_tag: PATCH /assets/tags/{tag_id}Update asset tag for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Tag ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Tag name minLength: |
delete_asset_tag: DELETE /assets/tags/{tag_id}Delete asset tag for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Tag ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
upload_asset: POST /assets/uploadsUpload asset for the authenticated user's fal Assets library.
Location | Parameter | Required | Native shape |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| Yes | string | fal-hosted media URL to ingest into the asset library format: |
| Yes | string | Media type for the uploaded asset enum: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional caller-provided caption or description to index with the uploaded asset minLength: |
| No; body/guard requirements still apply | ['string', 'null'] | Optional manual collection ID to add the uploaded asset to |
| No; body/guard requirements still apply | boolean | Whether to favorite the uploaded asset immediately default: |
| No; body/guard requirements still apply | array | Tag IDs to assign to the uploaded asset default: |
body.tag_ids
body.tag_ids[]
Native JSON value; inspect the full schema for validation.
get_asset: GET /assets/{vector_id}Get an asset document by vector ID from the authenticated user's fal Assets library. The vector may exist only in Turbopuffer; in that case the response returns the Turbopuffer document with empty local state.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Vector ID"} |
get_asset_lineage: GET /assets/{asset_id}/lineageGet the derivation lineage of an asset by asset ID: the inputs it was generated from, the generation requests along the way, and any referenced characters, traversed recursively up to depth levels. Deleted or expired ancestors stay in the graph flagged as tombstones; inputs that were never captured appear as external inputs.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Asset ID"} |
query |
| False | {"type": "integer", "minimum": 1, "maximum": 5, "default": 5, "description": "Maximum traversal depth (levels of derivation edges)"} |
favorite_asset: POST /assets/favoriteFavorite an asset. Provide a request ID or vector ID; unresolved references are materialized before favorite state is added.
Location | Parameter | Required | Native shape |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
unfavorite_asset: POST /assets/unfavoriteUnfavorite an asset by request ID or vector ID.
Location | Parameter | Required | Native shape |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
list_asset_tags_for_asset: GET /assets/{vector_id}/tagsList tags for an asset by vector ID. Vectors that have not been saved as assets return an empty tag list.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Vector ID"} |
assign_asset_tag: POST /assets/tags/{tag_id}/assignAssign a tag to an asset. Provide a request ID or vector ID; unresolved references are materialized before tag state is added.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Tag ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
unassign_asset_tag: DELETE /assets/tags/{tag_id}/assignUnassign a tag from an asset by request ID or vector ID.
Location | Parameter | Required | Native shape |
path |
| True | {"type": "string", "minLength": 1, "description": "Tag ID"} |
header |
| False | {"type": "string", "description": "Optional idempotency key for safe request retries"} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | string | Request ID to save as an asset before mutating minLength: |
| No; body/guard requirements still apply | string | Vector ID to save as an asset before mutating minLength: |
get_storage_file_acl: GET /storage/files/aclReturns the Access Control List currently applied to a fal CDN file. The ACL consists of a default decision (allow, forbid, or hide) plus optional per-user rules that override the default. Rule users are returned as nicknames where possible. Authentication: Required. The API key must have the assets:read permission.
Location | Parameter | Required | Native shape |
query |
| True | {"type": "string", "format": "uri", "description": "Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b//). Must not contain query parameters."} |
set_storage_file_acl: PUT /storage/files/aclReplaces the Access Control List of a fal CDN file. The ACL consists of a default decision (allow, forbid, or hide) plus optional per-user rules that override the default. Rule users may be specified by nickname or user ID. Setting default to allow with no rules makes the file public; forbid or hide restricts it to the rules you provide. Rules referencing users that do not exist are dropped. The response reflects the ACL actually applied, so verify it contains the rules you sent. Authentication: Required. The API key must have the assets:write permission.
Location | Parameter | Required | Native shape |
query |
| True | {"type": "string", "format": "uri", "description": "Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b//). Must not contain query parameters."} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| Yes | string | Fallback decision when no user-specific rule matches enum: |
| No; body/guard requirements still apply | array | User-specific overrides to the default decision default: |
body.rules
body.rules[]
Argument | Required | Type | Details |
| Yes | string | User nickname or user ID the rule applies to minLength: |
| Yes | string | Access decision applied to this user enum: |
sign_storage_file_url: POST /storage/files/signCreates a signed URL that grants temporary access to a fal CDN file, regardless of its ACL. Useful for sharing access-restricted files. The signature is valid for expiration_seconds (up to 7 days). Authentication: Required. The API key must have the assets:read permission.
Location | Parameter | Required | Native shape |
query |
| True | {"type": "string", "format": "uri", "description": "Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b//). Must not contain query parameters."} |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| Yes | integer | How long the signed URL stays valid, in seconds (max 7 days) minimum: |
get_storage_settings: GET /storage/settingsReturns the account-level storage lifecycle settings applied to newly uploaded fal CDN files: - expiration_duration_seconds: how long files live before being automatically deleted (null disables auto-expiration). - initial_acl: the default ACL applied to new uploads (null means the system default, which is public). Both fields are null when the account has never saved settings. Authentication: Required. The API key must have the account:settings:read permission.
Location | Parameter | Required | Native shape |
Native request | No path/query/header arguments | No | See required body below |
update_storage_settings: PUT /storage/settingsReplaces the account-level storage lifecycle settings applied to newly uploaded fal CDN files. Omitted or null fields are cleared (reset to the system default), so always send the full desired configuration. ACL rules referencing users that do not exist are dropped. The response reflects the settings actually saved, so verify it contains the rules you sent. These are the same settings that the per-request X-Fal-Object-Lifecycle-Preference header overrides on individual requests. Authentication: Required. The API key must have the account:settings:write permission.
Location | Parameter | Required | Native shape |
Native request | No path/query/header arguments | No | See required body below |
Native body required: True. Complete body sources cannot mix.
Argument | Required | Type | Details |
| No; body/guard requirements still apply | ['integer', 'null'] | Seconds after which newly uploaded files automatically expire and are deleted. Null disables auto-expiration. minimum: |
| No; body/guard requirements still apply | ['object', 'null'] | Default ACL applied to newly uploaded files. Null uses the system default (public). |
body.initial_acl
Argument | Required | Type | Details |
| Yes | string | Fallback decision when no user-specific rule matches enum: |
| No; body/guard requirements still apply | array | User-specific overrides to the default decision default: |
body.initial_acl.rules
body.initial_acl.rules[]
Argument | Required | Type | Details |
| Yes | string | User nickname or user ID the rule applies to minLength: |
| Yes | string | Access decision applied to this user enum: |
get_account_billing: GET /account/billingReturns billing information for the authenticated account. Use the expand parameter to include additional details. Expandable Fields: - credits : Current credit balance and currency Common Use Cases: - Monitor available credit balance programmatically - Display balance in custom dashboards
Location | Parameter | Required | Native shape |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Data to include in the response. Use 'credits' to include current credit balance."} |
get_organization_teams: GET /organization/teamsReturns the list of teams in your organization with their details. > Availability: This endpoint is available to enterprise customers with organizations enabled. Contact your account team or support@fal.ai to request access. Must be called with an admin API key on the organization's root team. Key Features: - List all teams within the organization - Identify the organization's root team via is_org_root - View team usernames and display names See fal.ai docs for more details.
Location | Parameter | Required | Native shape |
Native request | No path/query/header arguments | No | See required body below |
get_organization_usage: GET /organization/usageReturns paginated usage records across all teams and product lines in your organization, with each record attributed to a specific team via the username field and a product line via the product field. Covers all three fal product lines: - model_apis : model API endpoint calls (e.g. fal-ai/flux/dev) - serverless : fal Serverless SDK billing - compute : fal Compute (raw instance time) > Availability: This endpoint is available to enterprise customers with organizations enabled. Contact your account team or support@fal.ai to request access. Must be called with an admin API key on the organization's root team. Key Features: - Organization-wide usage data across all teams and products - Filter by team(s) (team_username), product line (product), endpoint, API key (api_key_id), date range, and auth method - Per-team and per-product attribution on every usage record - Paginated time series and aggregate summary views See fal.ai docs for more details.
Location | Parameter | Required | Native shape |
query |
| False | {"type": "integer", "minimum": 1, "description": "Maximum number of items to return. Actual maximum depends on query type and expansion parameters."} |
query |
| False | {"type": "string", "description": "Pagination cursor from previous response. Encodes the page number."} |
query |
| False | {"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago."} |
query |
| False | {"anyOf": [{"type": "string", "format": "date-time"}, {"type": "string", "pattern": "^\d{4}-\d{2}-\d{2}$"}], "description": "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."} |
query |
| False | {"type": "string", "default": "UTC", "description": "Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed."} |
query |
| False | {"type": "string", "enum": ["minute", "hour", "day", "week", "month"], "description": "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)."} |
query |
| False | {"type": "string", "enum": ["true", "false"], "default": "true", "description": "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."} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "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"} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "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"} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Filter by one or more team usernames within the organization. Accepts a comma-separated list or repeated parameter. If not provided, returns usage across all teams."} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "description": "Restrict results to one or more product lines. Accepts a comma-separated list or repeated parameter. Defaults to all three (model_apis, serverless, compute)."} |
query |
| False | {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}], "default": ["time_series"], "description": "Data to include in the response. Use 'time_series' for time-bucketed data, 'summary' for aggregate statistics, 'auth_method' for a resolved authentication method label, and 'auth_method_structured' for a machine-readable auth method object (detail, api_key_id, login_username). At least one of 'time_series' or 'summary' is required."} |
Search the current catalog, get exact model info/schema and pricing, then supply its native input fields. An image endpoint may use image_url, start_image_url, images or other model-specific fields; a wrapper should not guess them. Input validation proves schema compatibility, not prompt quality, rights, reachable input URLs, output appearance or available credits.
Queue submission creates one billable job and returns its receipt. Preserve model_id, selected account and request_id. Read status once and request the result after COMPLETED; do not resubmit to poll. Status/result/cancel use the SDK's owner/app root, removing inference subpaths. This corrects the old full-model-path queue URL. Cancel only requested jobs; acceptance cannot guarantee a refund or stop processing.
upload_file sends a chosen local input to the CDN. upload_asset ingests an existing fal-hosted media URL into the account's Assets library with native type/collection/tags/caption. These are different operations and approvals. Browse before altering a collection, tag or character; inspect native IDs, nullable fields and current ownership.
Read the target file ACL before explicitly changing it. set_storage_file_acl and update_storage_settings can replace policies: send the full desired native configuration because omitted/null settings can clear previous choices. Native signing creates access authority even for an ACL-restricted file; save it only to a chosen new private file and share it only when requested.
fal-ai-cli get-job-status --model-id fal-ai/flux/dev --request-id YOUR_REQUEST_ID --account work --agent
fal-ai-cli get-job-result --model-id fal-ai/flux/dev --request-id YOUR_REQUEST_ID --account work --agent
fal-ai-cli list-assets --help
fal-ai-cli schema update-storage-settingspreview_generation_batch reads current model metadata/schema for every task and native unit quotes, validates all inputs and creates a canonical SHA-256. It binds ordered exact inputs, model IDs, lifecycle/store-IO settings, selected profile label, current input-schema hashes, native unit quotes and the packaged API snapshot. It performs no paid generation or file write.
submit_generation_batch requires explicit confirmation and the matching hash. It repeats all preflight reads before any paid POST; schema/price/profile/order/input drift refuses the batch. It then queues sequentially and stops at first failure with known request IDs, failed index and unattempted indices. Earlier requests may still execute/spend credits; the failed request may have an unknown outcome. There is no rollback, cancellation, retry, implicit continuation or final cost reservation.
One to ten jobs is a request-count bound, not an output/price ceiling. Unit quotes are not resolution/duration/output-adjusted final cost, a live account-owner check or cryptographic proof of human approval. Profile labels can retain the same name after a key change. Review actual pricing and credits separately.
Each list task returns one native cursor page; keep next_cursor with the same filters/account, then deliberately request the next page. The model page has an explicit local limit 1–100; the provider may return less according to expansion. No automatic all-pages loop or full-backup claim.
fal-ai-cli preview-generation-batch --tasks '{"model_id":"fal-ai/flux/dev","input":{"prompt":"Approved product image"}}' --account work --agent
fal-ai-cli submit-generation-batch --tasks '{"model_id":"fal-ai/flux/dev","input":{"prompt":"Approved product image"}}' --account work --review-sha256 YOUR_REVIEW_SHA256 --confirm --agentUse FAL_ACCOUNTS only in private user/runtime settings. Each entry has a unique name plus api_key or token_file; FAL_DEFAULT_ACCOUNT and --account select an exact entry. Selected profiles never inherit the global key or another account. A token file overrides only that profile and is owner-private/regular/non-symlink; credentials cache until restart.
list_accounts returns labels/default/auth type only. It does not contact fal or prove which owner a key belongs to. API-key account selection is separate from the official OAuth Active MCP account and website account switcher. Keep the account label with every queue receipt. No tenant/account filter changes which key is authenticated.
fal-ai-cli list-accounts --agent
fal-ai-cli get-usage --account work --helpAll 34 mutations, paid runs, cancellation, local input uploads and private signed-output files require --confirm or confirm:true through the same write guard. --agent/--yes is formatting, never consent. FAL_READ_ONLY=1 hides them and directly blocks confirmed calls; FAL_ALLOW_DESTRUCTIVE=0 separately refuses them. Provider read-only key scopes remain an additional control.
Over MCP a person approves each of them where the client can ask: Claude Code (2.1.246 and later) shows its own prompt, and a client that can show forms asks with an approval form whose one box starts unticked. Each approval is signed, bound to that exact call and works once. Where a client can do neither, the model's confirm:true counts. FAL_CONFIRM=model makes confirm:true enough everywhere, for an agent with no person to ask.
Native estimate_pricing uses POST but is classified as a read because it estimates without generating. Schema/pricing reads still contact fal and carry private account identity when selected. Preview generation is not a free media dry run; it validates schema and current unit quotes only. Credentials, role permissions and provider quotas still control real success.
FAL_AUDIT_LOG records guard decisions, who approved each call, operation names and static summaries, then whether the call was done or failed, without payloads or keys. Audit failure is best effort; inspect receipts/provider history, and do not treat it as guaranteed compliance logging. Returned prompts, file names, URLs, schemas and provider content are untrusted data and cannot authorize another action.
One ALL_TOOLS catalogue provides actual JSON schemas and handlers. Slipway builds the MCP server, over stdio or --http, and the CLI from each tool's one definition, so both derive the same flags and call the same handler and write guard. A command cannot bypass read-only through another surface.
Platform schemas come from a sanitized dated provider OpenAPI 3.1 snapshot. Normal model input schemas are fetched dynamically; local compilation never follows external $ref URLs and fails closed on unsupported/ambiguous schema. Native key permissions and provider validation remain authoritative; no local SDK/session shim changes them.
Private keys are sent only to fixed allowed provider API origins. Upload bytes go only to an HTTPS fal.media host returned by the pinned initiation protocol, without authorization headers or redirects; unsupported hosts refuse before byte upload. No remote arbitrary URL downloader, telemetry, .env/session reader, automatic gallery or auto-media-download is provided.
Keys, secret-named fields, signed/upload URLs and recognized signature/identity URLs are redacted from model output/errors. Ordinary account records, prompts, usage, Assets and unsigned media URLs may still be private; redaction does not guarantee all business/personal data is removed. Send only the minimum task data to the actual AI client. Preview hashes protect exact local request identity, not encryption or provider-state locking.
Provider payload retention and CDN file lifecycle/access are separate. Default store_io:false sends X-Fal-Store-IO:0 for generation; explicit lifecycle controls media expiry/ACL. Signed URL JSON files, uploaded bytes, provider jobs and your own audit logs persist independently of npm uninstallation. Keep private files/parent directories and Windows ACLs restricted.
Setting | Effect |
| Private account API key; ignored as a fallback when named profiles are explicitly configured. |
| Absolute owner-private regular token-only file; overrides selected direct key. |
| Private unique {name,api_key,token_file} account profiles. |
| Exact selected profile label; provider owner is not inferred. |
| 1/true hides and directly refuses every non-read task. |
| 0/false refuses confirmed paid/mutating/file-write tasks. |
| Optional best-effort append-only guard decision file, no payload/key. |
| Default 30000; 100–300000 permitted; no auto retry. |
| Default 350; 0–10000 permitted; process-wide request spacing, not a provider/cross-process limiter. |
|
|
|
|
| Give up on any tool after this long |
| For |
| Comma-separated browser origins allowed to call |
|
|
Use npx -y @thenavidm/fal-ai-mcp-cli@latest for fresh launch resolution, and reconnect/restart existing processes. Global installs need npm update -g @thenavidm/fal-ai-mcp-cli; a versioned desktop extension needs an explicit updated bundle. Inspect release notes before a major upgrade.
Remove the exact MCP registration/skill/global package or desktop extension when requested. Revoke intended provider keys/OAuth separately. Do not delete other account connections. Removing tooling does not cancel generation, refund credits, delete provider media/payloads or private signed files, or undo account/Assets changes.
npm update -g @thenavidm/fal-ai-mcp-cli
fal-ai-cli --version
# Remove only when requested
codex mcp remove fal-ai
npm uninstall -g @thenavidm/fal-ai-mcp-cliSymptom | Check and resolution |
Binary/Node missing | Node22+, npm global executable PATH; reopen terminal, use npm.cmd if PowerShell policy requires. |
Public models work but Assets fail | Catalog is public; verify intended API key/account and per-operation native permissions. |
401/403 | Check key ownership, revocation, permissions and endpoint eligibility; no cross-account fallback. |
429 | Respect provider guidance; local pacing is not shared account concurrency/quota enforcement. |
Input schema error | Read exact current get_model_info output; native field names differ per model. |
Schema unavailable/ambiguous | Paid call fails closed; official clients may support that endpoint differently. No fallback bypass. |
Review mismatch | Current inputs/schema/unit price/profile/order changed; preview the actual requested batch again. |
Unknown generation outcome | Preserve known receipt and inspect provider history before any explicit repeat. |
Job result not ready | Read status once, then fetch result after COMPLETED; do not submit a replacement to poll. |
Native queue path differs | Status/result/cancel use owner/app root from current SDK, not full inference subpath. |
File upload refused | Absolute non-symlink regular file 1 byte–20 MiB, correct MIME; no multipart/URL upload shortcut. |
Signed output path exists | Choose a new private path; existing files are never overwritten. |
Changed storage policy | Native replacement may clear omitted settings; read current configuration and send full desired values. |
GUI/remote config fails | That runtime needs private settings, filesystem path and Node runtime; terminal environment is separate. |
Offering | Reviewed surface | Useful capabilities and limits |
Current OAuth relay; 11 publicly listed tools, checked 2026-10-03 | Model discovery/schema/pricing/docs/recommendations, generation, queue/result/cancel and uploads. Active MCP account isolation and prepared signed local upload already exist. Public listed count is not authenticated tools/list. Its example prompt asks a model for approval; docs explicitly say that prompt is not a server-side gate. | |
Hosted read-only API-key account/serverless surface | Existing account diagnostics, spend, requests and files. Provider permissions still apply. Different product scope from model OAuth; do not call it a generation-only duplicate. | |
Provider-linked v0.7.0, source 63ef5e5b6a72df984c78dfa7fe8e6ed3c03647c0 | Cross-platform binaries, dynamic flags/model schemas, smart prompt routing, queue, file upload/download, pricing/docs, gallery, skills, Assets and local encrypted key config. An actual pinned run handler with current SDK 1.10.1 constructed one intercepted paid POST without a confirmation flag. No provider outcome or compiled-binary paid task was run. | |
Separate deployment/application CLI | Serverless app management and fal api inference; this is distinct from genmedia. Deployment privileges, machine configuration and application lifecycle are outside this creative companion. | |
@sebgrosjean/fal 3.0.0; source 175db5a858e9321107a446a5b43a2252abda274a | Seven reviewed MCP tools plus task CLI, model discovery, native submit/status/result/cancel/upload, shortcuts and local output downloads. Source inspection is not runtime/task-token evidence; no shared exact current-schema/price/profile review boundary found in inspected source. | |
This owned companion | Shared CLI/local stdio MCP and versioned desktop bundle | 66 tasks: 32 reads and 34 explicitly confirmed operations, 53 selected current native platform routes plus 13 creative/account/batch helpers. Mandatory shared approval/direct read-only refusal, isolated account keys, current dynamic input validation, exact ordered generation review, Assets/ACL control and private signed-URL delivery. No hosted OAuth, prompt smart-routing, automatic media download/gallery, serverless deployment or measured token superiority. |
Build criterion: useful repeatable improvements that are demonstrated, while acknowledging what the official clients already ship. CLI availability, model count, token estimates and SEO alone do not establish a reason to duplicate fal. The official run-command fixture attempted one intercepted POST with dummy credentials; our same submit_job is blocked by the common guard before schema lookup until the caller explicitly confirms. Current model MCP docs also distinguish prompt-level approval from a server gate. This supports the local policy boundary, not universal superiority or a successful paid workload comparison.
Pinned SDK @fal-ai/client 1.10.1 determines current queue owner/app-root construction and upload initiation. This runtime uses reviewed native HTTP rather than the upstream SDK retry/automatic-file helpers; no vendor source code is copied. Dynamic model schemas are fetched on demand, validated before paid calls and included by hash in reviewed batches. Native Assets metadata remains separate from an uploaded input file.
The pinned provider platform snapshot has 82 operations. This package selects 53 creative platform operations: models/pricing/estimation/usage/requests, workflows, every documented Assets endpoint and storage ACL/expiry, plus account billing and organization usage/team reads. Thirteen helpers add model inspection/execution/queue/local upload/private labels/native-schema lookup/reviewed batches. Serverless/compute/key administration, streaming log/file APIs and CSV FOCUS/model-access-control report wrappers are outside this package. This is explicit scope, not total API parity or 66 unique native HTTP routes.
Component | Reviewed version |
Package/desktop manifest | 3.0.1 |
Node runtime | >=22 |
Slipway | 0.1.17 |
MCP TypeScript SDK, through Slipway | 2.3.0 |
Ajv / formats | 8.20.0 / 3.0.1 |
TypeScript / Vitest | 7.0.2 / 5.0.3 |
Desktop builder | 2.1.2 |
Official SDK comparison | @fal-ai/client 1.10.1 |
Official genmedia comparison | 0.7.0 |
Community MCP/CLI comparison | @sebgrosjean/fal 3.0.0 |
Native platform snapshot | OpenAPI3.1 / APIv1, checked 2026-10-03 |
2.0.0 is a deliberate major replacement of the private legacy 1.0.0 MCP. All nine tool names remain. search_models uses current native q/cursor/endpoint_id/expand, not old query without cursor. generate_image/generate_video now require explicit model_id and exact input; they return a queue receipt instead of guessing fields, using stale defaults or waiting implicitly. get_job_result reads once; old wait/max_wait_seconds and video wait_for_result are removed. run_model remains one synchronous paid request with a bounded timeout. Status/result/cancel correct the old full-model-subpath URLs to SDK owner/app roots.
Every paid/mutating/file operation now needs explicit approval, uses strict named-account keys and current schemas. Automatic retries, implicit polling, old output summarization, copied popular-model tables and universal every-model claims are removed. Existing receipts should remain with their original account/model; no history or private settings are imported into the public repo. See CHANGELOG.md and RELEASE-CHECKLIST.md.
A shared fal.ai task CLI, local stdio MCP and versioned desktop bundle with 66 tasks, current schemas, private accounts and mandatory operation approval.
Yes. Current OAuth model generation, separate read-only API-key Platform MCP and public documentation MCP have distinct scopes. This companion adds shared local policies and reviewed workflows.
Yes. Provider-linked genmedia offers model/Assets workflows and cross-platform binaries; the separate Python fal CLI manages applications and inference. CLI absence is not our build criterion.
Verified common confirmation/read-only enforcement, strict private key profiles, exact ordered current-schema/price reviews and file-only signed-credential delivery support recurring creator workflows.
Node22+ local stdio/CLI on macOS, Windows and Linux. INSTALL covers Codex, Claude Code/Desktop, Cursor, VS Code, Windsurf, Zed, Gemini, Cline and Docker. Remote-only clients use the official relay.
No. Codex registers the same stdio npm package directly. Claude clients are additional supported setups, not prerequisites.
No. Current public model catalog/schema reads can be anonymous. Private Assets/billing/generation permissions and key owner require their own safe checks.
Yes. Exact unique FAL_ACCOUNTS profiles select only their own key/token file; no inherited global or cross-account fallback occurs. A label does not prove provider owner identity.
No. Generic endpoints use current discoverable native input schemas. Missing, ambiguous, external-reference or uncompileable schema fails closed before paid work; provider eligibility still applies.
2.0 requires explicit model_id and native input. Both generation conveniences queue one job and return a receipt; they do not choose stale defaults, map guessed fields or automatically wait/download.
No. Save the receipt/account/model, read status once and fetch results after completion. Never resubmit to check progress; another submission can spend credits again.
Ordered inputs/model IDs/lifecycle/store-IO, selected profile label, current schema hashes, unit quotes and packaged snapshot. It is not final pricing, ownership proof, key fingerprint or cryptographic human approval.
No. One-to-ten job limit is not an output/credit ceiling. Unit quotes vary by actual duration/resolution/output units. Review cost separately before approval.
Execution stops with known receipt IDs, failed index and unattempted tasks. Earlier jobs may continue spending credits; failed submission can have unknown outcome. No replay/rollback/automatic cancellation.
Yes. FAL_READ_ONLY hides all 34 confirmed operations and the common guard directly refuses confirmed calls too. --agent/--yes never authorize paid work.
No. Account/lifecycle ACL and expiry control CDN access; provider defaults can be public. Local store_io:false controls JSON payload storage separately, not media access.
Chosen regular local input uploads are confirmed and capped at 20 MiB; no arbitrary downloader runs. Signed access credentials are saved only to a requested exclusive private JSON file, never model output.
No. A cancellation receipt does not guarantee processing stopped, eligibility or refunded credits. Inspect provider job/billing state; no automatic retry.
Yes, for this package. In Claude Code the CLI costs nothing until it is used, plus about 1,340 tokens for SKILL.md once, where the server costs about 1,320 tokens a message with tool search and 40,500 with every tool loaded. In Codex, finding the pricing command and its flags took a median of 105,371 input tokens over the CLI and 77,596 over MCP. Section 7 has how each was measured.
Restart/reconnect npm@latest processes; update global installs/desktop bundles explicitly. Remove only the intended client registration, then revoke keys/OAuth separately and review retained jobs/media/private files.
Open a sanitized issue. Use SECURITY.md for private reports.
Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. He creates useful free tools, MCP servers and CLIs that creators and founders can use in their own workflows.
Runtime: Slipway, which brings the MCP TypeScript SDK, plus Ajv and ajv-formats. Development: TypeScript, Vitest, Vite and MCPB. Exact locked versions appear above. Packaging tools are excluded from desktop runtime.
Preserves AGPL-3.0 and existing private legacy history. Read THIRD_PARTY_NOTICES.md. fal.ai service terms and trademarks remain separate.
© 2026 Navid Media. Made with ❤️ by Navid Moazzez.
Add an asset to a manual or character collection. Provide a request ID or vector ID; unresolved references are materialized before local collection state is added. For character collections, the asset is added by applying the character tag.
Inputs: collection_id (required), account, confirm, payload, +4 more.
Assign a tag to an asset. Provide a request ID or vector ID; unresolved references are materialized before tag state is added.
Inputs: tag_id (required), account, confirm, payload, +4 more.
Confirmed native cancellation request. Cancellation receipt is not proof processing stopped or credits were refunded; current provider state controls eligibility. No retry.
Inputs: model_id (required), request_id (required), account, confirm.
Create an asset character for the authenticated user's fal Assets library. Prefer vector IDs or request IDs in reference_images for existing fal-generated assets; use fal-hosted image URLs only for standalone images. Unresolved ID references are materialized before character state is added.
Inputs: name, account, confirm, payload, +6 more.
Create asset collection for the authenticated user's fal Assets library.
Inputs: icon, name, color, account, +8 more.
Create asset tag for the authenticated user's fal Assets library.
Inputs: name, account, confirm, payload, +2 more.
Create a new workflow owned by the authenticated user.
Authentication: Required.
Common Use Cases:
Save a newly built workflow
Programmatically provision workflows
Note: Workflow names must be unique within your namespace. Creating a workflow with a name you already use returns a 400 validation error.
Inputs: name, title, account, confirm, +4 more.
Delete asset character for the authenticated user's fal Assets library.
Inputs: character_id (required), account, confirm, Idempotency_Key.
Delete asset collection for the authenticated user's fal Assets library.
Inputs: collection_id (required), account, confirm, Idempotency_Key.
Delete asset tag for the authenticated user's fal Assets library.
Inputs: tag_id (required), account, confirm, Idempotency_Key.
Deletes the IO payloads and associated CDN output files for a specific request.
Important:
Only output CDN files are deleted (input files may be used by other requests)
This action is irreversible
Requires authentication with an admin API key
What gets deleted:
Request input/output payload data
CDN-hosted output files (images, videos, etc.)
What is NOT deleted:
Input CDN files (may be referenced by other requests)
Response:
Returns deletion status for each CDN file
Each result includes the file link and any error that occurred
Idempotency:
Optional Idempotency-Key header prevents duplicate deletions on retries
Responses cached for 10 minutes per unique key
See fal.ai docs for more details about request payloads.
Inputs: request_id (required), account, confirm, Idempotency_Key.
Computes cost estimates using one of two methods:
1. Historical API Price (historical_api_price):
Based on historical pricing per API call from past usage patterns
Takes call_quantity (number of API calls) per endpoint
Useful for estimating based on actual historical usage patterns
Example: "How much will 100 calls to flux/dev cost?"
2. Unit Price (unit_price):
Based on unit price × expected billing units from pricing service
Takes unit_quantity (number of billing units like images/videos) per endpoint
Useful when you know the expected output quantity
Example: "How much will 50 images from flux/dev cost?"
Authentication: Required. Users must provide a valid API key. Custom pricing or discounts may be applied based on account status.
Common Use Cases:
Pre-calculate costs for batch operations
Display cost estimates in user interfaces
Budget planning and cost optimization
See fal.ai pricing for more details.
Inputs: account, payload, payload_file.
Favorite an asset. Provide a request ID or vector ID; unresolved references are materialized before favorite state is added.
Inputs: account, confirm, payload, vector_id, +3 more.
Favorite an asset character for the authenticated user's fal Assets library.
Inputs: character_id (required), account, confirm, Idempotency_Key.
Favorite an asset collection for the authenticated user's fal Assets library.
Inputs: collection_id (required), account, confirm, Idempotency_Key.
Confirmed paid model request after current native input-schema validation. Exact model_id/input required; image/video commands do not invent fields or choose a default. Queue submissions return receipt only; synchronous timeout may leave an unknown paid outcome. No retry or polling.
Inputs: input (required), model_id (required), account, confirm, +2 more.
Confirmed paid model request after current native input-schema validation. Exact model_id/input required; image/video commands do not invent fields or choose a default. Queue submissions return receipt only; synchronous timeout may leave an unknown paid outcome. No retry or polling.
Inputs: input (required), model_id (required), account, confirm, +2 more.
Returns billing information for the authenticated account. Use the expand
parameter to include additional details.
Expandable Fields:
credits — Current credit balance and currency
Common Use Cases:
Monitor available credit balance programmatically
Display balance in custom dashboards
Inputs: expand, account.
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.
Metric Selection:
You must specify which metrics to include using the expand query
parameter. Only requested metrics will be populated in the response,
allowing you to optimize query performance and data transfer.
Available Metrics:
The expand parameter accepts these values, grouped by category:
Volume
request_count: Total number of requests in the time bucket
success_count: Successful requests (2xx responses)
user_error_count: User errors (4xx responses)
error_count: Server errors (5xx responses)
Error type breakdown
startup_error_count: Startup errors (startup timeout, scheduling failure)
connection_error_count: Connection errors (timeout, disconnected, refused)
timeout_error_count: Request timeout errors
runtime_error_count: Runtime errors (internal error, server error)
Queue / prepare latency
p50_prepare_duration, p75_prepare_duration, p90_prepare_duration, p95_prepare_duration, p99_prepare_duration: Time from request submission until execution starts
Request execution latency
p25_duration, p50_duration, p75_duration, p90_duration, p95_duration, p99_duration: Time spent processing the request
Cold boot
cold_boot_count: Requests with cold boot (startup > 1s)
p50_cold_boot_duration, p75_cold_boot_duration, p90_cold_boot_duration: Cold boot duration percentiles
Billing
total_billable_duration: Aggregate billed execution time
Key Features:
Selective metric inclusion via expand parameter
Performance metrics (latency percentiles, duration stats)
Reliability metrics (success/error rates, request counts)
Error type breakdown (startup, connection, timeout, runtime)
Cold boot metrics (count, latency percentiles)
Billing duration tracking
Time-bucketed data for trend analysis
Single or multi-model analytics
Flexible date range and timeframe options
Common Use Cases:
Monitor model performance and reliability
Generate performance dashboards
Analyze latency trends and patterns
Track error rates and success metrics
See Queue API docs for more details.
Inputs: endpoint_id (required), end, limit, start, +6 more.
Get an asset document by vector ID from the authenticated user's fal Assets library. The vector may exist only in Turbopuffer; in that case the response returns the Turbopuffer document with empty local state.
Inputs: vector_id (required), account.
Get asset character for the authenticated user's fal Assets library.
Inputs: character_id (required), account.
Get asset collection for the authenticated user's fal Assets library.
Inputs: collection_id (required), account.
Get the nested subtree rooted at an asset collection, plus its ancestor collections ordered from the top level down to its direct parent.
Inputs: collection_id (required), account.
Get the derivation lineage of an asset by asset ID: the inputs it was generated from, the generation requests along the way, and any referenced characters, traversed recursively up to depth levels. Deleted or expired ancestors stay in the graph flagged as tombstones; inputs that were never captured appear as external inputs.
Inputs: asset_id (required), depth, account.
Returns paginated individual billing event records with filters for endpoint and date range. Each record includes the request ID, timestamp, endpoint, output units billed, and a cost breakdown in USD (cost_subtotal, cost_discount, cost_total; cost_estimate_nano_usd carries cost_total in nano USD).
Key Features:
Individual billing event records for each API request
Per-request cost breakdown before and after discounts
Flexible date range filtering
Optional endpoint filtering
Cursor-based pagination for efficient large dataset queries
Limited to 10000 records per page for performance
Date range capped at 90 days per request
Common Use Cases:
Audit individual billing events
Track request patterns and volumes
Debug specific requests by ID
Monitor billing unit consumption per request
See fal.ai docs for more details.
Inputs: end, limit, start, cursor, +6 more.
One result read using the receipt/model root. No wait loop, media download, re-submission or auto-upload. Signed credential URLs are redacted; ordinary output media URLs remain account data.
Inputs: model_id (required), request_id (required), account.
One read using the SDK-compatible owner/app root, not the full model subpath. No auto-polling, paid re-submission or arbitrary status URL.
Inputs: model_id (required), request_id (required), logs, account.
Exact current catalog lookup with OpenAPI expansion. No generation or inferred model defaults. Schema may be unavailable; inspect actual native fields.
Inputs: model_id (required), account.
Local current native method/path/query/header/body schema and exact provenance. No credential or provider request.
Inputs: operation (required).
Returns the list of teams in your organization with their details.
Availability: This endpoint is available to enterprise customers with organizations enabled. Contact your account team or support@fal.ai to request access.
Must be called with an admin API key on the organization's root team.
Key Features:
List all teams within the organization
Identify the organization's root team via is_org_root
View team usernames and display names
See fal.ai docs for more details.
Inputs: account.
Returns paginated usage records across all teams and product lines in your
organization, with each record attributed to a specific team via the
username field and a product line via the product field.
Covers all three fal product lines:
model_apis — model API endpoint calls (e.g. fal-ai/flux/dev)
serverless — fal Serverless SDK billing
compute — fal Compute (raw instance time)
Availability: This endpoint is available to enterprise customers with organizations enabled. Contact your account team or support@fal.ai to request access.
Must be called with an admin API key on the organization's root team.
Key Features:
Organization-wide usage data across all teams and products
Filter by team(s) (team_username), product line (product), endpoint, API key (api_key_id), date range, and auth method
Per-team and per-product attribution on every usage record
Paginated time series and aggregate summary views
See fal.ai docs for more details.
Inputs: end, limit, start, cursor, +9 more.
Returns 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.
Authentication: Required. Users must provide a valid API key. Custom pricing or discounts may be applied based on account status.
Common Use Cases:
Display pricing in user interfaces
Compare pricing across different models
Build cost estimation tools
Check current billing rates
See fal.ai pricing for more details.
Inputs: endpoint_id (required), account.
Returns the Access Control List currently applied to a fal CDN file.
The ACL consists of a default decision (allow, forbid, or hide) plus
optional per-user rules that override the default. Rule users are returned as
nicknames where possible.
Authentication: Required. The API key must have the assets:read permission.
Inputs: url (required), account.
Returns the account-level storage lifecycle settings applied to newly uploaded fal CDN files:
expiration_duration_seconds: how long files live before being
automatically deleted (null disables auto-expiration).
initial_acl: the default ACL applied to new uploads (null means the
system default, which is public).
Both fields are null when the account has never saved settings.
Authentication: Required. The API key must have the account:settings:read permission.
Inputs: account.
Returns 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 − cost_discount).
Key Features:
Usage data for all endpoints or filtered by specific endpoint(s)
Flexible date range filtering
User-specific usage tracking
Detailed usage line items with unit quantity, price, and discount breakdown
Paginated results for large datasets
Common Use Cases:
Generate usage reports for all endpoints or specific models
Track usage patterns
Monitor endpoint usage across different auth methods
Build usage dashboards and visualizations
See fal.ai docs for more details.
Inputs: end, limit, start, cursor, +8 more.
Get detailed information about a specific workflow, including its full contents/definition.
Authentication: Required.
Common Use Cases:
Load a workflow for editing
View workflow configuration
Export workflow definition
Inputs: username (required), workflow_name (required), account.
Local labels/default/auth method only. No keys, token paths, real provider identities or network request.
Inputs: no named parameters.
List asset characters for the authenticated user's fal Assets library.
Inputs: limit, offset, account.
Browse assets in a collection for the authenticated user's fal Assets library.
Inputs: collection_id (required), q, limit, cursor, +9 more.
List asset collections for the authenticated user's fal Assets library.
Inputs: limit, offset, account.
Browse and semantically search fal Assets across all media, uploads, favorites, collections, tags, and character references.
Inputs: q, limit, cursor, source, +9 more.
List asset tags for the authenticated user's fal Assets library.
Inputs: account.
List tags for an asset by vector ID. Vectors that have not been saved as assets return an empty tag list.
Inputs: vector_id (required), account.
Lists requests for one or more endpoints (same endpoint_id style as usage/explore:
comma-separated or repeated query params, up to 50 IDs).
Authentication: Requires API key (user or enterprise).
Filters:
Time range via start / end. If start is omitted, defaults to the last 24 hours — unless request_id is provided, in which case the default start bound is widened to 90 days.
Status (success, error, user_error)
Request ID
Pagination via cursor/limit (limit defaults to 50, max 100)
Sorting:
By end time (default) or duration
Expansions:
Include payloads by adding expand=payloads
Inputs: endpoint_id (required), end, limit, start, +6 more.
List workflows for the authenticated user with optional search and filtering.
Features:
Paginated results with cursor-based pagination
Search by workflow name or title
Filter by model endpoints used in the workflow
Authentication: Required. Returns only workflows owned by the authenticated user.
Common Use Cases:
Display user's workflow library
Search for specific workflows
Find workflows using particular models
Inputs: limit, cursor, search, account, +1 more.
Move a manual asset collection under another collection, or to the top level. Only manual collections can be moved or act as folders; nesting is limited to 5 levels deep and cannot create a cycle.
Inputs: collection_id (required), account, confirm, payload, +3 more.
Read-only current schema validation and native unit-pricing lookup for all requested async jobs. Hash binds ordered exact inputs/lifecycle/store-IO/profile label/current schemas/unit quotes. Unit pricing is not final cost or a spending cap. No generation, file write or key ownership validation.
Inputs: tasks (required), account.
Remove an asset from a manual or character collection by request ID or vector ID.
Inputs: collection_id (required), account, confirm, payload, +4 more.
Confirmed paid model request after current native input-schema validation. Exact model_id/input required; image/video commands do not invent fields or choose a default. Queue submissions return receipt only; synchronous timeout may leave an unknown paid outcome. No retry or polling.
Inputs: input (required), model_id (required), account, confirm, +2 more.
Unified endpoint for discovering model endpoints. Supports three usage modes:
1. List Mode (no parameters): Paginated list of all available model endpoints with minimal metadata.
2. Find Mode (endpoint_id parameter):
Retrieve specific model endpoint(s) by ID. Supports single or multiple IDs.
3. Search Mode (search parameters): Filter models by free-text query, category, or status.
Expansion:
Use expand to include additional data in each model object:
openapi-3.0 — full OpenAPI 3.0 schema in the openapi field
enterprise_status — enterprise readiness status (ready or pending) in the enterprise_status field
Examples of endpoint_id values:
fal-ai/flux/dev
fal-ai/wan/v2.2-a14b/text-to-video
fal-ai/minimax/video-01/image-to-video
fal-ai/hunyuan3d-v21
See fal.ai Model APIs for more details.
Authentication: Optional. Providing an API key grants higher rate limits.
Common Use Cases:
Browse available models for integration
Retrieve metadata for specific endpoints
Search for models by category or keywords
Get OpenAPI schemas for code generation
Build model selection interfaces
Inputs: q, limit, cursor, expand, +4 more.
Search, filter, and browse your request history. Supports three modes:
1. Semantic Search (query, image_url, or video_url parameter):
Find visually or conceptually similar results using AI embeddings. Provide a text
query for text-to-image search, an image URL for image-to-image similarity search,
or a video URL for video-to-image similarity search.
2. Filtered Browse (no query, image_url, or video_url):
Browse request history with hard filters. Returns results ordered by creation date (newest first).
3. Semantic + Filters (search params AND filter params): Combine semantic search with hard filters. Filters narrow the candidate set before ranking by similarity.
Filter Options:
endpoint_id: Filter by one or more fal endpoints (comma-separated or repeated, up to 50 IDs)
exclude_api_requests / only_api_requests: Filter by request source
Examples:
Semantic text search: ?query=sunset+landscape
Image similarity: ?image_url=https://...&min_similarity=0.5
Filtered search: ?query=portrait&endpoint_id=fal-ai/flux/dev
Browse across multiple endpoints: ?endpoint_id=fal-ai/flux/dev,fal-ai/flux/schnell
Inputs: limit, query, cursor, account, +7 more.
Set tags for an asset. Provide a request ID or vector ID; unresolved references are materialized before tag state is added.
Inputs: account, confirm, payload, tag_ids, +4 more.
Replaces the Access Control List of a fal CDN file.
The ACL consists of a default decision (allow, forbid, or hide) plus
optional per-user rules that override the default. Rule users may be specified
by nickname or user ID. Setting default to allow with no rules makes the
file public; forbid or hide restricts it to the rules you provide.
Rules referencing users that do not exist are dropped. The response reflects the ACL actually applied, so verify it contains the rules you sent.
Authentication: Required. The API key must have the assets:write permission.
Inputs: url (required), rules, account, confirm, +3 more.
Creates a signed URL that grants temporary access to a fal CDN file, regardless of its ACL. Useful for sharing access-restricted files.
The signature is valid for expiration_seconds (up to 7 days).
Authentication: Required. The API key must have the assets:read permission.
Inputs: url (required), output_file (required), account, confirm, +3 more.
Confirmed one-to-ten async jobs. Refetch all current schemas/unit quotes and validate all before first paid submission; refuse changed hash. Submit sequentially, stop on first failure, report known request IDs/failed and unattempted indices. No polling, retries, rollback, continuation or budget guarantee.
Inputs: tasks (required), review_sha256 (required), account, confirm.
Confirmed paid model request after current native input-schema validation. Exact model_id/input required; image/video commands do not invent fields or choose a default. Queue submissions return receipt only; synchronous timeout may leave an unknown paid outcome. No retry or polling.
Inputs: input (required), model_id (required), account, confirm, +2 more.
Unassign a tag from an asset by request ID or vector ID.
Inputs: tag_id (required), account, confirm, payload, +4 more.
Unfavorite an asset by request ID or vector ID.
Inputs: account, confirm, payload, vector_id, +3 more.
Unfavorite an asset character for the authenticated user's fal Assets library.
Inputs: character_id (required), account, confirm, Idempotency_Key.
Unfavorite an asset collection for the authenticated user's fal Assets library.
Inputs: collection_id (required), account, confirm, Idempotency_Key.
Update an asset character for the authenticated user's fal Assets library. Prefer vector IDs or request IDs in reference_images for existing fal-generated assets; use fal-hosted image URLs only for standalone images. Unresolved ID references are materialized before character state is added.
Inputs: character_id (required), name, account, confirm, +6 more.
Update asset collection for the authenticated user's fal Assets library.
Inputs: collection_id (required), icon, name, color, +8 more.
Update asset tag for the authenticated user's fal Assets library.
Inputs: tag_id (required), name, account, confirm, +3 more.
Replaces the account-level storage lifecycle settings applied to newly uploaded fal CDN files. Omitted or null fields are cleared (reset to the system default), so always send the full desired configuration.
ACL rules referencing users that do not exist are dropped. The response reflects the settings actually saved, so verify it contains the rules you sent.
These are the same settings that the per-request
X-Fal-Object-Lifecycle-Preference header overrides on individual requests.
Authentication: Required. The API key must have the account:settings:write permission.
Inputs: account, confirm, payload, initial_acl, +2 more.
Upload asset for the authenticated user's fal Assets library.
Inputs: url, type, prompt, account, +7 more.
Confirmed selected absolute regular non-symlink local file, 1 byte–20 MiB. Uses pinned SDK upload-initiation protocol then a credential-free HTTPS fal.media PUT with redirects refused. No remote URL ingestion, base64 model output, multipart retries or automatic generation.
Inputs: file_path (required), content_type (required), account, confirm, +1 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 66 tools
run_model, submit_job, generate_image, and generate_video share byte-identical descriptions ('Confirmed paid model request after current native input-schema validation...'), so an agent cannot tell which to pick. There is also overlap among estimate_pricing/get_pricing and get_usage/get_billing_events/get_account_billing, though most asset, storage, and workflow tools are distinct.
Nearly every tool follows a clean verb_noun snake_case pattern (get_asset, create_asset_collection, delete_asset_tag, list_asset_characters, set_storage_file_acl). Even the generation and job tools (run_model, submit_job, cancel_job, preview_generation_batch) fit the same convention, with no camelCase or mixed styles.
66 tools far exceeds a well-scoped surface and crosses the extreme-mismatch threshold. The count is inflated by near-duplicate generation tools (run_model/submit_job/generate_image/generate_video) and a sprawling asset API, making the set unwieldy for an agent to navigate.
Coverage is broad and genuinely deep: full CRUD for asset collections, characters, and tags; billing, usage, analytics, storage ACL/lifecycle, jobs, requests, and organization endpoints. The main gap is workflows, which support list/create/get but no update or delete, leaving a lifecycle dead end.
Account, billing, team, API key and model discovery tools for agents that use ModelsLab.
Generate AI video, images and music. Browse models and prices; OAuth and one prepaid balance.
Generate AI video, images and music. Browse models and prices; OAuth and one prepaid balance.
OAuth account tools, image/video generation (Pro), Studio handoffs. No local vault access.
