fal

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

Fetch the result for a completed fal.ai queue job. 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 before running expensive models (video, training) to estimate costs. 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.

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

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

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

move_collection

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

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; it does not upload or generate. Use upload_file first for external files. For model results include requestId and endpoint to preserve generation provenance. Use the returned assetRecordId to organize the asset.

save_asset

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

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

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

Link or unlink associated gallery media. This does not add or remove a defining reference image; use update_entity for that.

set_entity_asset

Use this to display completed fal images or videos. First obtain a completed run_model or get_job_result response; pass its exact result, endpoint_id, request_id and recipe when available. Never generate or resubmit a job just to display media. This render-only tool does not fetch jobs or recover missing recipes.

show_media

Submit a job to the queue WITHOUT waiting for completion. Returns immediately with a request_id. Use this instead of run_model for long-running tasks (video generation, 3D, training). Then use check_job to poll status and get_job_result to retrieve the result when ready.

submit_job

Upload a file to fal.ai's CDN so it can be used as input to models. Provide exactly one source: - PUBLIC URL → pass a publicly accessible HTTP(S) file URL as 'url'. - LOCAL FILE (preferred, up to 90MB) → call with 'prepare_upload': true, 'file_name' (basename with extension) and 'file_size' in bytes. Then use your local HTTP tool to PUT the raw file bytes to the returned signed upload_url. No separate API key is needed. This server cannot read your local paths. - DIRECT UPLOAD → 'prepare_upload': true prepares a signed PUT; it does not upload the file. Supply 'file_name' and 'file_size', with no 'url', 'data', or 'file_path'. Only use file_url after the local PUT succeeds. Requires local file and HTTP access; otherwise ask for a public URL. - BASE64 (small files only) → programmatically pass complete file bytes encoded as 'data', preferably with 'file_name'. Do not print, copy, invent or truncate base64 in the conversation. Prefer direct upload for local files. Uploads use this connection's authenticated fal account. Do not request a different API key or switch accounts to work around a rejection.

upload_file