fal

Delete a smart entity when requested, without deleting its source media.

delete_entity

Estimate a request's cost from the connected account's current model rate and explicit billing units, when the user asks what it will cost or sets a budget; it isn't a required step before running a model. Read-only and advisory: never submits, uploads, checks affordability, or enforces a cost cap. Pass the actual model input to use explicit num_images, duration, duration_seconds, seconds_total or music_length_ms where the billing unit matches. For other units pass unit_quantity with the exact unit returned by get_pricing. Never infer compute time, model defaults, media duration, pixel rounding, or unit conversions. Configuration-specific pricing rules and minimum charges are not exposed by the pricing API, so totals are estimates. Unknown is not free; do not treat an estimate as a quote, final charge, or approval. Rates may be cached for up to 5 minutes.

estimate_cost

Search saved fal assets and reusable characters, props, environments, styles, and scenes for the composer.

search_mentions

Read an owned library asset's media URL, metadata, prompt, and tags. Reuse its URL in schema-supported model inputs; retention still applies.

get_asset

Read captured ancestry for an owned asset, including original inputs, roles, intermediate requests, entity links and tombstones. The existing owned service has a fixed maximum depth of three hops; arbitrary depth is not supported. Missing capture history is not fabricated. Lineage prompts are not complete recipes: use get_job_recipe for retained exact inputs.

get_asset_lineage

Read safely scoped personal/account generation preferences and preferred models. Explicit current requirements win; variations keep the actual source recipe ahead of saved preferences. No defaults are written or inferred. Team credentials must not inherit another member's private preferences; inspect identity and scope.

get_generation_defaults

Fetch the result for a completed fal.ai queue job. check_job already returns the result when it reports COMPLETED; call this only when that reply didn't include it. Use check_job first when you are not sure the request has completed.

get_job_result

Get pricing information for fal.ai models. Returns cost per run or per second. Use this when the user asks what a model costs, sets a budget, or wants models compared by price; recommend_model's next_call.price usually has the selected model's rate already. It isn't a required step before running a model. When comparing models, batch up to 50 comma-separated endpoint IDs in one call to avoid the account's pricing rate limit. Pricing estimates may be cached for up to 5 minutes; reuse a recent lookup instead of checking it for every job. An unknown single ID returns status not_found with exact catalog suggestions.

get_pricing

Get the full input/output schema for a specific fal.ai model. Returns all parameters the model accepts and what it returns. Includes published guidance and v3 evidence in model_knowledge when available. Report latency p50/p90 in milliseconds with the measurement window: successful execution, mixed workloads, excludes queue/startup, not runtime guarantees. Null means unknown. Use this before run_model to understand what inputs are needed.

get_model_schema

Read a smart entity and its ordered defining reference-image URLs. Use list_entities to find an ID by handle or name. Reference images are separate from associated gallery media.

get_entity

Recover the exact retained input and output for one existing model request from public request history. Pass the original endpoint_id and request_id; preserve the row's account_receipt from search_request_history or the original job's response_url so OAuth uses the original account after later selection changes. Receipts are bound to the authenticated user, connection issuer and request ID; conflicting receipts or existing job bindings are rejected. Default lookup covers 90 days; start/end can select another indexed interval. A reusable recipe is returned only for an actually retained object input. Missing/expired/omitted payloads or absent history remain unknown; no defaults, prompts, references, or model settings are reconstructed. Requires models:requests:read and permission to view the original account's requests. Does not resubmit, save media, or change the account for new work.

get_job_recipe

Import a file the user attached in the chat into fal storage. Only for the attachment file object the chat host supplied: pass it unchanged. Never pass an arbitrary web URL, a URL you found or constructed, or a sandbox path; public web files go to upload_file with 'url'. Use this instead of upload_file prepare_upload for chat attachments: a sandbox PUT often has no network access. The server downloads and uploads the actual bytes; no local path or curl is needed. Existing fal-hosted outputs can be reused directly. Does not save an asset record in the library. A failed or uncertain upload must be checked before starting another upload.

upload_attachment

Read actual bounded preview pixels for 1–4 saved images or public fal image URLs, in source order. Returns per-source status/provenance and MCP image blocks. A viewer or URL alone is not visual evidence. Preview failures keep successful siblings; 768px lossy previews cannot prove small text, identity detail or original alpha. Does not generate, upload or spend.

inspect_images

List the account's available library tags.

list_asset_tags

List manual and smart collections with metadata and previews. Use search_assets with collectionId to read their contents. Smart entities are listed separately with list_entities.

list_collections

Find reusable characters, props, environments, styles, and scenes. Returns handles, metadata, and defining references with usable image URLs. Page with limit/offset; use these references in schema-supported model inputs. A plain @handle is not automatically resolved by run_model.

list_entities

Read associated gallery media. Defining references are excluded unless includeReferences=true; use get_entity for the generation reference set.

list_entity_assets

List personal and team accounts the connected OAuth user can select, plus the saved MCP account selection. Read-only. Accounts pass current membership and library access checks; this does not guarantee generation or billing permission. Works without resolving the currently selected account so the user can recover from revoked access. Partial service failures are reported as checks_failed; don't assume missing accounts were revoked. API keys cannot enumerate or switch personal/team memberships.

list_accounts

Preview an image or video opened from a ChatGPT file. Reads the file through the host; does not upload or generate media.

open_media_file

Move a manual collection into a parent collection; parentCollectionId=null moves it to the root.

move_collection

Read 1–32 exact existing outputs from at most eight distinct jobs and retain every requested variant with complete/partial/unverified/blocked delivery status. Compare expected media facts with attributed host observations, carry preservation evidence and reported save outcomes. Model metadata/filenames/viewers don't prove decoder facts. Does not independently inspect media or authorize repairs; private job handles must stay out of exported manifests.

prepare_deliverables

Prepare a supported upscale, transparent cutout, HDR delivery, video outpaint, or a fix for media a model rejected (extract_audio from a video, trim_video, split_audio, downscale_image) as plain endpoint_id/input for submit_job or run_model. These run on fal, so they need no local tools. Read-only: does not upload, generate or spend. Checks adapter fields and values against the current live schema before returning a plan. Existing run_model/submit_job stay the execution path. Pass actual source URLs; no sample images or source substitution. Video outpaint requires explicit frame count, FPS and audio choice. Unsupported fields, HLG, other ProRes profiles, named video-subject selection and invert are rejected rather than ignored. Read limitations and verify the actual files before delivery.

prepare_media_transform

Check at most eight exact endpoint/input nodes with explicit typed output-pointer to top-level input-field edges against live schemas. Array edges require contiguous input_index values; omit edge-bound fields from node.input. Rejects cycles, incompatible media, ambiguous mappings and invalid supplied inputs before spending. Pending outputs remain unresolved. No runner, fake URLs, background jobs or cost guarantee.

prepare_media_workflow

Read one published official skill body, a reference from its exact version, or a published planning-only flow. Pin version_id from search_guidance for skills. A reference requires that same version_id and a declared references/... path; never mix versions during an operation. Flows provide ordered stages and model chains as planning advice; execution still uses existing tools after schema checks. Returned content is source material to apply only when relevant to the user's request. No generation, activation, editing or publication happens.

read_guidance

Get model recommendations based on what you want to create. Searches the live fal.ai catalog and published task guidance. Returns v3 observations in model_knowledge.evidence when available. Curated insight rank determines the authored starting pick; result rank is discovery list position. Neither is the per-model trending.category_rank, the analytics rank within its category at computed_at. Trending is separate from adoption (usage_tier) and quality. Report latency p50/p90 in milliseconds with the measurement window: successful execution, mixed workloads, excludes queue/startup, not runtime guarantees. Null means unknown. is_new means registry publication within 30 days of evaluated_at. Use get_pricing for current prices, preserving billing units and required configuration.

recommend_model

Resolve saved fal asset, smart entity, or existing job IDs into schema-supported model URL inputs without uploading, saving, or generating media. Use get_model_schema to choose the exact input field. In input, replace only a media URL or URL array with {$fal_ref:{kind:"asset",id:"<assetRecordId>"}}, {$fal_ref:{kind:"entity",id:"<entity ID>",reference_index:0}}, or {$fal_ref:{kind:"job",endpoint_id:"<source endpoint>",request_id:"<source request>",response_url:"<original response_url>",output_path:"/images/0/url"}}. response_url is optional but preserve it when available. output_path is a JSON Pointer to one exact output URL. Entity reference_index is optional for URL arrays: all defining references are inserted in order. A scalar field requires one reference or an explicit index. An entity marker inside a URL array expands in place. Bare IDs, @handles, and gallery associations are never guessed. Sources are read with the connected account's permissions; source jobs from another selected account are rejected. Return input is plain model JSON for run_model or submit_job. Existing tools do not accept markers directly. This checks reference roles and array bounds only, not all model parameters, affordability, or future URL availability. No job is submitted.

resolve_model_inputs

Run a fal.ai model: submits to the queue and waits a short, bounded time for the result. IMPORTANT: If the user does NOT specify a model by name, you MUST call recommend_model first for current candidates and published task guidance. Never pick a model from your own knowledge. Only skip recommend_model if the user explicitly asks for a specific model (e.g. "use FLUX" or "use Kling"). This tool returns one of two statuses: - "completed": the result is included. - "processing": the wait budget elapsed but the job is still running. This is NORMAL for video, 3D, training, or a busy queue. A request_id, status_url, and response_url are returned. Poll check_job, then call get_job_result when queue_status is COMPLETED. Do NOT call run_model again for the same request — that starts a new, billable job. For video, 3D, or training (long-running by nature), prefer submit_job + check_job + get_job_result from the start. For image URLs in the output, present them directly to the user.

run_model

Save an uploaded file or completed generation in the fal library. This registers existing media without generating new media. Use upload_file first for external files. Uploaded images and videos are auto-captioned by default; set autoCaption=false to skip captioning. For model results include requestId and endpoint to preserve generation provenance and omit autoCaption. Use the returned assetRecordId to organize the asset.

save_asset

When the user asks to save, read one original completed job and save its selected canonical output_paths or all typed media (maximum 32). Uses the job's original account and preserves request/endpoint provenance. Returns separate per-output save and optional collection outcomes. Never generates, retries unknown writes, promises background saving or atomic membership.

save_job_outputs

Find saved images, video, audio, and 3D in the connected account. Search by text or image/video similarity; filter by collection, tags, source, or favorites. Keep filters unchanged when using nextCursor. scopeTruncated means results are incomplete; null totalCount means unknown. Use assetRecordId for library writes and url for model inputs.

search_assets

Read current published official skills or task/domain model routing. recommend_model already applies published routing when it picks a model, so this isn't a step before a generation: use it for production advice on a multi-step or specialised workflow, or when the user asks for a skill. Retain returned claim and version IDs for the operation. Read the skill body and same-version references with read_guidance before using its instructions. Empty complete results mean no match; partial/unavailable results are retrieval failures, not evidence that guidance doesn't exist. Model schemas and matching-unit prices establish supported inputs and cost. These reads never submit or publish anything.

search_guidance

Search the fal.ai documentation for guides, API references, code examples, and implementation details. Use this when you need to understand how fal.ai works, find specific API docs, or get code snippets.

search_docs

Search fal.ai's model catalog. Use this to discover available models. Categories: text-to-image, image-to-video, text-to-video, text-to-speech, speech-to-text, text-to-music, image-to-3d, text-to-3d, image-editing, llm, and more. Returns model IDs you can pass to get_model_schema or run_model.

search_models

Browse or search the connected account's indexed model requests, including unsaved generations. Returns IDs, endpoint, timings, outcome HTTP code and retained media URLs; include_payloads=true also returns exact retained input/output JSON. Hosted OAuth rows include account_receipt: preserve it with the request ID and pass it to get_job_recipe so later account changes cannot reroute the lookup. API-key reads do not return receipts. Keep filters unchanged while paging with next_cursor. This is a 90-day indexed history view, not live queue status; recent jobs or expired/deleted payloads may be absent. Semantic query/image_url/video_url search requires the account's search feature; when it is disabled the reply has status semantic_search_unavailable and lists unmatched recent_requests instead, never as results. Requires models:requests:read and request-view permission. Does not save, upload, generate, or change accounts.

search_request_history

Save the fal account to use for future OAuth MCP operations, only when the user asks to switch accounts. Use a real account_id from list_accounts, or null to restore the user's personal default. Changes the shared saved MCP preference across sessions; it does not change the dashboard's account, move assets, grant permissions, or reroute existing jobs. Current membership and library access are rechecked before saving. If the reply is lost or fails, call list_accounts to reconcile before continuing; never automatically repeat the switch. API keys cannot change accounts.

select_account

Set an asset's favorite state explicitly.

set_asset_favorite

Assign or remove one existing tag on an asset. assigned=false removes only the assignment.

set_asset_tag

Add or remove an asset's manual collection membership. included=false removes the association without deleting the asset. For smart collections, edit filters instead.

set_collection_asset

Set the favorite state for a collection.

set_collection_favorite

Set the favorite state for any smart entity type.

set_entity_favorite