--- title: fal API Integration on Truto slug: fal category: Artificial Intelligence canonical: "https://truto.one/integrations/detail/fal/" --- # fal API Integration on Truto **Category:** Artificial Intelligence **Status:** Beta ## MCP-ready AI tools Truto exposes 74 tools for fal that AI agents can call directly. - **list_all_fal_models** — List and search fal model endpoints. Returns a model object with endpoint_id and metadata. No required parameters. Supports filtering by endpoint_id, q, category, status, and expand. - **list_all_fal_models_pricings** — List pricing for fal model endpoints. Returns: next_cursor, has_more, prices. Accepts 1-50 endpoint IDs. Required: endpoint_id. - **create_a_fal_pricing_estimate** — Estimate usage costs for fal endpoints. Returns: estimate_type, total_cost, currency. Use historical_api_price with call_quantity per endpoint, or unit_price with unit_quantity per endpoint. - **list_all_fal_models_usages** — List fal model usage records for your workspace. Returns paginated time_series buckets, next_cursor, and has_more. Optional: start, end, endpoint_id, api_key_id, login_username, timeframe, expand. - **list_all_fal_models_analytics** — List time-bucketed analytics for fal model endpoints. Returns time_series buckets with per-bucket metrics (request_count, success_count, latency percentiles, error breakdowns), plus next_cursor and has_more. Use expand to choose which metrics are populated. Required: endpoint_id. - **list_all_fal_models_billing_events** — List individual billing events in fal. Returns: next_cursor, has_more, billing_events. Date range capped at 90 days and max 10,000 records per page. - **fal_request_payloads_bulk_delete** — Delete request payloads and CDN output files for a specific fal.ai request. Returns: cdn_delete_results. Only output CDN files are deleted; input files may be shared with other requests. This action is irreversible. Required: request_id. - **list_all_fal_models_requests_by_endpoints** — List requests by endpoint for one or more fal models. Returns: request_id, endpoint_id, started_at, sent_at, ended_at, status_code, duration, json_input, json_output. Accepts 1-50 endpoint IDs as comma-separated values. Defaults to the last 24 hours unless request_id is provided. Required: endpoint_id. - **list_all_fal_serverless_requests_by_endpoints** — List serverless requests for one or more fal endpoints owned by the authenticated user. Returns: request_id, endpoint_id, started_at, sent_at, ended_at, status_code, duration, json_input, json_output, runner_id, billable_units. Supports 1–50 endpoint IDs. Required: endpoint_id. - **list_all_fal_requests_searches** — Search and filter your fal request history. Supports semantic search via query, image_url, or video_url; filtered browse; or a combination of both. Returns request items with request_id, endpoint_id, started_at, sent_at, status_code, and duration. Optional: endpoint_id, endpoint, exclude_api_requests, only_api_requests, min_similarity. query, image_url, and video_url are mutually exclusive. - **list_all_fal_workflows** — List workflows for the authenticated fal user. Returns: name, title, user_nickname, created_at, thumbnail_url, description, tags, endpoint_ids. Supports optional search by name or title and filtering by used_endpoint_ids. - **create_a_fal_workflow** — Create a new workflow in fal. Returns the created workflow including name, title, user_nickname, created_at, is_public, and contents. Workflow names must be unique within your namespace. Required: name, title, contents. - **get_single_fal_workflow_by_id** — Get detailed information about a specific fal workflow, including its full contents/definition. Returns the workflow object including its name, title, user_nickname, created_at, is_public, and contents. Required: username, workflow_name. - **list_all_fal_assets** — Browse and semantically search fal assets across media, uploads, favorites, collections, tags, and character references. Returns asset records with vector_id, request_id, url, type, title, endpoint, created_at, source, prompt, width, height, content_type, is_favorited, collection_ids, tags, and similarity. - **get_single_fal_asset_by_id** — Get a single fal asset by vector id. Returns the asset object under the `asset` key, including vector_id, request_id, url, type, title, endpoint, created_at, source, prompt, width, height, content_type, is_favorited, collection_ids, tags, and similarity. Required: id. - **list_all_fal_asset_tags** — List asset tags for a fal asset by vector id. Returns each tag with id, name, and created_at. Vectors not saved as assets return an empty list. Required: vector_id. - **list_all_fal_assets_collections** — List asset collections in the authenticated user's fal Assets library. Returns: collections, name, description. - **create_a_fal_assets_collection** — Create an asset collection in the authenticated user's fal Assets library. Returns: collection, name, description. Required: name. - **get_single_fal_assets_collection_by_id** — Get an asset collection by id from the authenticated user's fal Assets library. Returns: collection, id, type, name, description, icon, color, cover_image_url, character_identifier, parent_collection_id, is_favorited, filters, asset_count, created_at, updated_at. Required: id. - **update_a_fal_assets_collection_by_id** — Update an asset collection by id in the authenticated user's fal Assets library. Returns: collection, id, type, name, description, icon, color, cover_image_url, character_identifier, parent_collection_id, is_favorited, filters, asset_count, created_at, updated_at. Required: id. - **delete_a_fal_assets_collection_by_id** — Delete an asset collection by id from the authenticated user's fal Assets library. Returns an empty 204 response on success. Required: id. - **create_a_fal_collection_favorite** — Favorite an asset collection in the authenticated user's fal Assets library. Returns the collection object with its id, name, type, is_favorited status, and timestamps. Required: collection_id. - **create_a_fal_collection_unfavorite** — Unfavorite an asset collection in fal. Returns the collection with id, name, type, is_favorited, and updated_at. Required: collection_id. - **create_a_fal_collection_move** — Move a manual asset collection in fal under another collection or to the top level. Returns the moved collection object including its id, type, name, parent_collection_id, and updated_at. Only manual collections can be moved; nesting is limited to 5 levels and cannot create a cycle. Required: collection_id, parent_collection_id. - **list_all_fal_collection_assets** — Browse assets in a fal collection. Returns: assets, next_cursor, has_more, total_count. Supports semantic text/image/video search and filters for media_type, source, section, tag_id, and tag_mode. Required: collection_id. - **create_a_fal_collection_asset** — Add an asset to a fal collection. Returns: success. Provide either request_id or vector_id. Required: collection_id. - **fal_collection_assets_bulk_delete** — Remove an asset from a fal collection. Returns an empty 204 response on success. Provide either request_id or vector_id. Required: collection_id. - **list_all_fal_assets_characters** — List asset characters in the authenticated user's fal Assets library. Returns each character's id, name, type, description, reference_images, is_favorited, created_at, updated_at, and asset_count. - **create_a_fal_assets_character** — Create an asset character in the authenticated user's fal Assets library. Returns the new character object including id, name, type, description, reference_images, created_at, and updated_at. Required: name, description, reference_images. - **get_single_fal_assets_character_by_id** — Get a single asset character by id from the authenticated user's fal Assets library. Returns the character object including id, name, type, description, reference_images, created_at, and updated_at. Required: id. - **update_a_fal_assets_character_by_id** — Update an asset character in the authenticated user's fal Assets library. Returns the updated character object including id, name, type, description, reference_images, created_at, and updated_at. Required: id. - **delete_a_fal_assets_character_by_id** — Delete an asset character by id from the authenticated user's fal Assets library. Returns an empty 204 response on success. Required: id. - **create_a_fal_character_favorite** — Favorite a fal asset character in the authenticated user's Assets library. Returns the favorited character object including its id, name, is_favorited, created_at, and updated_at. Required: character_id. - **create_a_fal_character_unfavorite** — Unfavorite a character in fal Assets. Returns the `character` record with id, name, type, is_favorited, and created_at. Required: character_id. - **list_all_fal_assets_tags** — List asset tags in the authenticated user's fal Assets library. Returns: id, name, created_at. - **create_a_fal_assets_tag** — Create an asset tag in the authenticated user's fal Assets library. Returns: tag, name. Required: name. - **fal_assets_tags_bulk_update** — Set the full replacement set of tags for an asset in fal. Returns: tags. Required: tag_ids. - **update_a_fal_assets_tag_by_id** — Update an asset tag in the authenticated user's fal Assets library. Returns: tag. Required: id. - **delete_a_fal_assets_tag_by_id** — Delete an asset tag in the authenticated user's fal Assets library by id. Returns an empty 204 response on success. Required: id. - **fal_assets_tags_assign** — Assign a tag to a fal asset. Provide a request_id or vector_id to identify the asset; unresolved references are materialized before the tag is added. Returns: success. Required: tag_id. - **fal_assets_tags_unassign** — Remove a tag from a fal asset. Provide a request_id or vector_id to identify the asset. Returns an empty 204 response on success. Required: tag_id. - **create_a_fal_assets_upload** — Upload a media asset to the authenticated user's fal Assets library. Returns the uploaded asset in the `asset` field (vector_id, type, url, created_at, tags, and collection_ids). Required: url, type. - **create_a_fal_assets_favorite** — Favorite an asset in fal by providing request_id or vector_id. Unresolved references are materialized before the favorite state is applied. Returns: is_favorited. - **create_a_fal_assets_unfavorite** — Unfavorite a fal asset by request_id or vector_id. Returns: is_favorited. - **list_all_fal_files_acls** — Get the Access Control List currently applied to a fal CDN file. Returns the ACL object including default decision and rules with per-user user and decision values. Required: url. - **fal_files_acls_bulk_update** — Replace the Access Control List of a fal CDN file. Returns the ACL object including default decision and rules with per-user user and decision values. Rules referencing unknown users are dropped. Required: url, default. - **create_a_fal_files_sign** — Create a signed URL for a fal CDN file. Returns: signed_url. expiration_seconds must be between 1 and 604800 seconds (7 days). Required: url, expiration_seconds. - **list_all_fal_storage_settings** — Get the account-level fal storage settings applied to newly uploaded CDN files. Returns: expiration_duration_seconds, initial_acl. Both fields are null if settings have never been saved. - **fal_storage_settings_bulk_update** — Replace the account-level fal storage settings for newly uploaded CDN files. Returns: expiration_duration_seconds, initial_acl.default, and initial_acl.rules. Send the full configuration because omitted or null fields are reset to system defaults. - **list_all_fal_serverless_analytics** — List time-bucketed analytics for your fal serverless endpoints. Returns time_series buckets and pagination fields next_cursor and has_more. expand must include at least one of time_series or summary plus a metric. Required: endpoint_id. - **list_all_fal_queues** — Get the current queue size for a specific fal application. Returns the app queue status object, which contains only queue_size, the number of pending requests. Required: owner, name. - **fal_queues_bulk_delete** — Flush all pending requests from a fal application queue. Returns an empty 204 response on success. This operation is irreversible and cancels pending requests; in-progress requests are not affected. Required: owner, name. - **list_all_fal_files_lists** — List files and folders in the root of your fal project storage. Returns: path, name, created_time, updated_time, is_file, size, checksum_sha256, checksum_md5. - **get_single_fal_files_list_by_id** — List files and folders in a specific fal project directory. Returns: path, name, created_time, updated_time, is_file, size, checksum_sha256, checksum_md5. Required: dir. - **list_all_fal_files** — Download a file from fal by its path. Returns the raw file stream as application/octet-stream. Required: file. - **create_a_fal_file_url** — Upload a file into fal from a publicly accessible URL. Returns a boolean indicating whether the upload was initiated successfully. Required: file, url. - **create_a_fal_file_local** — Upload a local file to fal. Returns a boolean success flag on completion. Optionally set unzip to true to extract ZIP uploads. Required: target_path. - **list_all_fal_serverless_metrics** — Get Prometheus-compatible serverless metrics from fal. Returns a plain-text Prometheus exposition format string containing runner, queue, request, and latency metrics. No caller parameters required. - **create_a_fal_logs_history** — Retrieve paginated historical log entries from fal. Returns: next_cursor, has_more, items. All query parameters are optional; label filter objects require key and value. - **create_a_fal_logs_stream** — Start a live Server-Sent Events stream of fal logs matching the provided filters. Returns a text/event-stream of log entries including timestamp, level, message, app, revision, and labels. - **list_all_fal_serverless_usages** — List time-bucketed serverless compute usage for your fal account. Returns next_cursor, has_more, and time_series with app, machine_type, quantity, cost, currency, and is_surge. Filter by start, end, app, search, timeframe, timezone, and expand. - **list_all_fal_compute_instances** — List compute instances in fal. Returns: next_cursor, has_more, instances. - **create_a_fal_compute_instance** — Create a new compute instance in fal. Returns the created instance including id, instance_type, region, and status. Required: instance_type, ssh_key. - **get_single_fal_compute_instance_by_id** — Get a single compute instance by id in fal. Returns: id, instance_type, region, sector, ip, status, creator_user_nickname. Required: id. - **delete_a_fal_compute_instance_by_id** — Delete a compute instance by id in fal. Returns an empty 204 response on success. Required: id. - **list_all_fal_keys** — List fal API keys in the authenticated workspace. Returns: next_cursor, has_more, keys. - **create_a_fal_key** — Create a new fal API key with a friendly alias. Returns: key_id, key_secret, key. The key_secret is returned only once. Required: alias. - **delete_a_fal_key_by_id** — Delete a fal API key by id. Returns an empty 204 response on success. Deletion is irreversible and idempotent. Required: id. - **list_all_fal_account_billings** — Get billing information for the authenticated fal account. Returns: username, credits. The credits object includes current_balance and currency when expanded. Optional: expand. - **list_all_fal_account_focus** — Download a FOCUS compliant billing report from fal. Returns a CSV report containing usage charges, credits, and taxes. Enterprise-only; usage estimates support a maximum 90-day lookback. Required: source. - **list_all_fal_account_model_access_controls** — Download the model access controls report for your fal organization. Returns a CSV string with endpoint ID, title, category, enterprise readiness, and resolved UI and API access states (ALLOWED or BLOCKED). Enterprise customers with model access controls enabled only. - **list_all_fal_organization_teams** — List all teams in your fal organization. Returns the teams array, where each team includes username, name, is_org_root, and created_at. Enterprise organizations only. - **list_all_fal_organization_usages** — List organization-wide usage records across all fal teams and product lines. Returns: next_cursor, has_more, time_series, summary. Supports filtering by team, product, endpoint, and date range. At least one of 'time_series' or 'summary' must be requested via expand. Enterprise-only. - **list_all_fal_metas** — Get platform metadata from fal. Returns: webhook_ip_ranges. ## How it works 1. **Link your customer's fal account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach fal.** The Proxy API is a 1-to-1 mapping of the fal API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Offer BYOA generative media inside your SaaS** — Let your customers connect their own fal accounts so your product can run image, video, and voice generation on their compute budget — without you managing GPU infrastructure or API keys. - **Pass through AI compute costs per tenant** — Pull fal's usage, pricing, and billing events into your platform to attribute exact per-run costs to each customer, deduct credits, or mark up compute in your own billing dashboard. - **Sync fal-generated assets into your DAM** — Mirror fal's assets, collections, characters, and tags into your product so users manage AI outputs alongside their existing content library instead of jumping between tools. - **Ship observability for AI workflows** — Surface latency, queue depth, and live logs from fal's serverless infrastructure inside your app so your users can debug generation pipelines without leaving your product. - **Provision dedicated compute for enterprise tenants** — For enterprise customers who need dedicated GPUs or hosted fine-tunes, programmatically create and manage fal compute instances scoped to each tenant. ## What you can build - **Dynamic model picker with cost preview** — Populate a model dropdown from list_all_fal_models and show users a live cost estimate via create_a_fal_pricing_estimate before they run a batch job. - **Character consistency library** — Let users register reference characters through create_a_fal_assets_character and reuse them across prompts for consistent avatars, mascots, or product models. - **Semantic asset search inside your app** — Expose fal's native text, image, and video similarity search via list_all_fal_assets so users can find similar generations without you running a vector database. - **Workflow orchestration for multi-step pipelines** — Create and trigger chained generation workflows using create_a_fal_workflow — for example background removal → variant generation → signed CDN delivery via create_a_fal_files_sign. - **Per-tenant AI spend dashboard** — Combine list_all_fal_models_usages, list_all_fal_models_billing_events, and list_all_fal_serverless_usages into a tenant-scoped cost report inside your billing UI. - **Live generation telemetry** — Stream fal.ai serverless metrics, queue status, and logs via list_all_fal_serverless_metrics, list_all_fal_queues, and create_a_fal_logs_stream to power a real-time debugging panel. ## FAQs ### How do end users authenticate their fal account? fal uses API key authentication. Your users generate a key in their fal dashboard and paste it into your app — Truto stores and rotates the credential per connected account, so your backend never handles it directly. ### Can we manage fal API keys programmatically? Yes. The list_all_fal_keys, create_a_fal_key, and delete_a_fal_key_by_id tools let you provision or revoke keys on behalf of a connected account, which is useful for scoping access per workspace or environment. ### How do we track cost per generation for billing passthrough? Use list_all_fal_models_pricings and create_a_fal_pricing_estimate for pre-run estimates, then reconcile with list_all_fal_models_usages and list_all_fal_models_billing_events after execution to get authoritative per-run costs. ### Does Truto support fal's real-time log streaming? Yes. create_a_fal_logs_stream exposes fal's live log stream, and create_a_fal_logs_history covers historical retrieval — you can pipe both into your own observability UI. ### Can we upload user files into fal from our app? Yes. Use create_a_fal_assets_upload, create_a_fal_file_url, or create_a_fal_file_local to push user content into fal's storage, and create_a_fal_files_sign to generate signed URLs for secure downstream access. ### How do we provision dedicated compute for enterprise customers? create_a_fal_compute_instance provisions a dedicated fal serverless instance, while get_single_fal_compute_instance_by_id and delete_a_fal_compute_instance_by_id let you inspect and tear down instances per tenant.