fal.ai MCP Server & CLI

What is the fal.ai MCP server & CLI?

The fal.ai MCP server & CLI is a free, open source program that lets AI agents read and change requested fal account/media data with explicit approval for you, in 2 ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call to fixed fal API origins with the selected private account key; local upload PUTs never receive that key.

The CLI is the same program as commands. fal-ai-cli search-models runs the same code your AI runs when you deliberately read one native model catalog page, whether an agent like Claude Code runs it or you do.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
Find current endpoint IDs and inspect the exact native model schema.
Read unit pricing and estimate the requested output quantities.
Review these ordered generation inputs and their exact hash.
Submit only that matching approved batch and save each request ID.
Read status once and fetch the existing result after completion.
Manage only these requested Assets and private signed-output files.

fal already provides an official OAuth model MCP, separate Platform MCP and provider-linked genmedia CLI with model and Assets workflows. This owned companion adds verified shared local confirmation/read-only rules, isolated API-key profiles, exact current-schema/unit-quote reviews and private signed-credential delivery.

How to install the fal.ai MCP server

Choose the shared task CLI, local stdio MCP or versioned desktop bundle. Codex setup comes first, followed by every declared client and operating system.

Set up fal.ai access

Private account access

1. Sign into the intended fal account. Confirm which personal/team account owns the credits and key before creating or copying it.
2. 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.
3. 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.
4. 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.
5. 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.

Official account connections

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.

Costs and permissions

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.

Data and file controls

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.

Rotation and revocation

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.

Check that it works

Start with local discovery/settings; deliberately opt into a public catalog read without generation.

fal-ai-cli --version
fal-ai-cli doctor
fal-ai-cli list-accounts --agent
fal-ai-cli doctor --network

fal-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 --agent

Public 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.

Use the fal.ai CLI

The CLI is the same 66 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so search_models runs as fal-ai-cli search-models.

fal-ai-cli tools
fal-ai-cli search-models --help
fal-ai-cli schema submit-job
fal-ai-cli search-models --limit 5 --agent
fal-ai-cli get-model-info --model-id fal-ai/flux/dev --agent

The bare fal-ai-cli lists every command, and fal-ai-cli <command> --help shows what a command takes. All 34 paid/mutating/upload/private-file operations require --confirm. --agent/--yes never approve work. Repeat --tasks with individual JSON objects; native bodies may use an absolute private payload_file.

These flags work on every command:

A script can branch on the exit code:

MCP server or CLI: which one?

Both surfaces call the same tools. Codex can connect to the local MCP server or run the CLI directly. Neither requires Claude Code.

MCP provides structured tool discovery; the CLI supports scripts, compact JSON, field selection and command/schema discovery. Official hosted MCP connection and local CLI authentication have different setup requirements.

Codex-specific token measurements are pending. Record the actual client/model versions, discovery configuration, input/output usage, caching, latency and equivalent successful outcomes. Standing definitions and full task cost are separate measurements; CLI commands, selected help, results and reasoning still consume tokens.

No efficiency percentage or Claude-derived figure is presented as a Codex result. Other-client benchmarks can be added separately.

Model and asset workflows

Deliberate model selection

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.

Receipt-driven generation

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.

Assets versus CDN files

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.

Private media access

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-settings

Exact reviewed generation batches and pagination

preview_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 --agent

Every fal.ai tool

Actual discovery exposes 66 tools: 32 reads and 34 confirmed operations. Fifty-three selected native platform operations and thirteen helpers share handlers. All nine legacy tool names remain with deliberate 2.0 breaking behavior/input corrections. Every native argument follows below.

Models

Workflows

Assets

Storage

Account

Organization

Creative Workflows

Is the fal.ai MCP server safe?

All 34 mutations, paid runs, cancellation, local input uploads and private signed-output files require --confirm or confirm:true through the same house 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.

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, operation names and static summaries, 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.

The review hash binds exact requests and current schema/unit quotes. It is not a final price budget, ownership proof, credit reservation or cryptographic human approval.

Make it read-only

FAL_READ_ONLY=1 exposes 32 reads and directly refuses all 34 confirmed operations. FAL_ALLOW_DESTRUCTIVE=0 blocks them separately; native provider permissions still apply.

Keep a log of every write

Set FAL_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked.

Your data

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.

Several private accounts

Use 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 --help

fal.ai MCP server settings

Keep keys, token files and profile JSON outside repositories. GUI/remote runtimes have separate environment and filesystems; no automatic .env, session or genmedia-config loader.

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.

Every tool argument and native input

search_models

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

Policy: Read/helper; no explicit mutation approval.

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_pricing

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.

Policy: Read/helper; no explicit mutation approval.

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_pricing

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.

Policy: Read/helper; no explicit mutation approval.

input.payload

input.payload oneOf branch 1

input.payload.oneOf1.endpoints

input.payload.oneOf1.endpoints.{key}

input.payload oneOf branch 2

input.payload.oneOf2.endpoints

input.payload.oneOf2.endpoints.{key}

get_usage

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.

Policy: Read/helper; no explicit mutation approval.

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_analytics

Time-bucketed metrics per model endpoint, including request counts, success/error rates, and latency percentiles. prepare_duration reflects queue/prepare time before execution; duration is request execution time. Use with the Queue/Webhooks flow to monitor SLAs. 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.

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_events

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.

Policy: Read/helper; no explicit mutation approval.

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_payloads

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.

Policy: Confirmed operation; read-only hides and directly refuses it.

list_requests_by_endpoint

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

Policy: Read/helper; no explicit mutation approval.

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_requests

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

Policy: Read/helper; no explicit mutation approval.

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_workflows

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

Policy: Read/helper; no explicit mutation approval.

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_workflow

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.

Policy: Confirmed operation; read-only hides and directly refuses it.

input.contents

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

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

input.payload.contents

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

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_workflow

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

Policy: Read/helper; no explicit mutation approval.

list_assets

Browse and semantically search fal Assets across all media, uploads, favorites, collections, tags, and character references.

Policy: Read/helper; no explicit mutation approval.

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_collections

List asset collections for the authenticated user's fal Assets library.

Policy: Read/helper; no explicit mutation approval.

create_asset_collection

Create asset collection for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

input.payload

get_asset_collection

Get asset collection for the authenticated user's fal Assets library.

Policy: Read/helper; no explicit mutation approval.

update_asset_collection

Update asset collection for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

input.payload

delete_asset_collection

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

Policy: Confirmed operation; read-only hides and directly refuses it.

get_asset_collection_hierarchy

Get 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.

favorite_asset_collection

Favorite an asset collection for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.