The Fal AI connector lets your AI agent act in each user's Fal AI account. Each user connects their own Fal AI API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 29 tools.
- Tools
- 29
- What they doRead · write · destructive
- 21 · 7 · 121 read7 write1 destructive
- Users sign in with
- API key
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Fal AI connection
In AgentKit > Connections, create a Fal AI connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'fal'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Fal AI:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'fal_browse_assets',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "fal"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Fal AI:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="fal_browse_assets",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Fal AI credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolfal_browse_assetsBrowse or semantically search the fal Assets library across uploads, generations, favorites and collections.Read-onlyBrowse Assets
Browse or semantically search the fal Assets library across uploads, generations, favorites and collections. Returns assets with asset_id, url, type, title, endpoint and created_at, plus a cursor for the next page. Use fal_get_asset for one asset.
Inputs
collection_idstring- Only assets in this collection.
cursorstring- Pagination cursor from the previous response's next_cursor. Keep all other filters unchanged while paging.
limitinteger- Maximum number of items to return per page.
qstring- Text query for semantic search.
search_image_urlstring- Image URL for visual similarity search.
search_video_urlstring- Video URL for visual similarity search.
sectionstring- Library section to browse. Defaults to all-media.one of
all-mediauploadsfavoritesgenerated
fal_estimate_costEstimate the cost of a planned workload on fal models.Read-onlyEstimate Cost
Estimate the cost of a planned workload on fal models. This only reads pricing and creates nothing. Returns estimate_type, total_cost and currency. Use before large runs; use fal_get_model_pricing for raw unit prices.
Inputs
endpointsobjectrequired- Object mapping each endpoint ID to its quantity. For historical_api_price use {"call_quantity": 100}; for unit_price use {"unit_quantity": 100}. Example: {"fal-ai/flux/dev": {"unit_quantity": 100}}.
estimate_typestringrequired- Estimation method: historical_api_price (cost per API call, endpoints map to call_quantity) or unit_price (unit price times billing units, endpoints map to unit_quantity).one of
historical_api_priceunit_price
fal_get_account_billingGet billing information for the authenticated fal account.Read-onlyGet Account Billing
Get billing information for the authenticated fal account. Returns username and, when expand includes credits, credits with current_balance and currency. Use to check the remaining credit balance.
Inputs
expandstring- Extra details to include. Use credits to include the credit balance.
fal_get_app_queue_sizeGet the number of requests currently waiting in a Serverless app's queue.Read-onlyGet App Queue Size
Get the number of requests currently waiting in a Serverless app's queue. Returns queue_size. Needs an API key with serverless queue read permission (SERVERLESS, READONLY or FULL preset).
Inputs
namestringrequired- App name.
ownerstringrequired- Owner (username or team) of the app.
fal_get_assetGet one asset from the fal Assets library by asset ID or vector ID.Read-onlyGet Asset
Get one asset from the fal Assets library by asset ID or vector ID. Returns the asset with asset_id, url, type, title, endpoint, source and created_at. Find IDs with fal_browse_assets.
Inputs
asset_idstringrequired- Asset ID (a vector ID is also accepted).
fal_get_asset_collectionGet one collection from the fal Assets library.Read-onlyGet Asset Collection
Get one collection from the fal Assets library. Returns the collection with id, type, name, icon, color, cover_image_url and parent_collection_id. Find IDs with fal_list_asset_collections.
Inputs
collection_idstringrequired- ID of the collection.
fal_get_model_analyticsGet time-bucketed request metrics for fal model endpoints.Read-onlyGet Model Analytics
Get time-bucketed request metrics for fal model endpoints. Returns buckets with request, success and error counts and latency percentiles per endpoint_id, plus next_cursor. Use for reliability and latency monitoring; use fal_get_model_usage for cost.
Inputs
endpoint_idstringrequired- Endpoint ID(s) to query, comma-separated (up to 50). Example: fal-ai/flux/dev,fal-ai/flux/schnell.
bound_to_timeframestring- Whether start and end are aligned to timeframe boundaries with an exclusive end. Defaults to true.one of
truefalse cursorstring- Pagination cursor from the previous response's next_cursor. Keep all other filters unchanged while paging.
endstring- End of the time range (exclusive), as an ISO 8601 date or datetime. Defaults to now.
expandstring- Metrics to include, comma-separated: time_series, request_count, success_count, error_count, p50_duration, p90_duration and similar. Defaults to time_series,request_count.
limitinteger- Maximum number of items to return per page.
startstring- Start of the time range, as an ISO 8601 date or datetime. Defaults to 24 hours ago.
timeframestring- Aggregation bucket size. Auto-detected from the date range when omitted.one of
minutehourdayweekmonth timezonestring- IANA timezone used to bucket dates, for example UTC or America/New_York.
fal_get_model_pricingGet unit pricing for one or more fal model endpoints.Read-onlyGet Model Pricing
Get unit pricing for one or more fal model endpoints. Returns prices with endpoint_id, unit_price, unit and currency. Use to compare model costs; use fal_estimate_cost to project the cost of a planned workload.
Inputs
endpoint_idstringrequired- Endpoint ID(s) to price, comma-separated (up to 50). Example: fal-ai/flux/dev,fal-ai/flux/schnell.
fal_get_model_usageGet billed usage of fal model endpoints over a time range.Read-onlyGet Model Usage
Get billed usage of fal model endpoints over a time range. Returns time_series buckets (or a summary) with endpoint_id, unit, quantity, unit price and cost, plus next_cursor. Needs an API key with billing permission (BILLING or FULL preset). Use fal_get_model_analytics for request counts and latency.
Inputs
bound_to_timeframestring- Whether start and end are aligned to timeframe boundaries with an exclusive end. Defaults to true.one of
truefalse cursorstring- Pagination cursor from the previous response's next_cursor. Keep all other filters unchanged while paging.
endstring- End of the time range (exclusive), as an ISO 8601 date or datetime. Defaults to now.
endpoint_idstring- Filter by one or more endpoint IDs, comma-separated (up to 50). Example: fal-ai/flux/dev,fal-ai/flux/schnell.
expandstring- Data to include, comma-separated: time_series (default), summary, auth_method.
limitinteger- Maximum number of items to return per page.
startstring- Start of the time range, as an ISO 8601 date or datetime. Defaults to 24 hours ago.
timeframestring- Aggregation bucket size. Auto-detected from the date range when omitted.one of
minutehourdayweekmonth timezonestring- IANA timezone used to bucket dates, for example UTC or America/New_York.
fal_get_request_resultFetch the output of a completed fal queue request.Read-onlyGet Request Result
Fetch the output of a completed fal queue request. Returns the model-specific result JSON, for example images, video or audio objects with media URLs. Call only after fal_get_request_status reports COMPLETED; app_id is the owner/alias part of the endpoint_id used at submit.
Inputs
app_idstringrequired- Application ID: only the first two segments (owner/alias) of the endpoint ID the request was submitted to. For fal-ai/flux/dev use fal-ai/flux.
request_idstringrequired- Request ID returned when the request was submitted to the queue.
fal_get_request_statusCheck the state of a queued fal request.Read-onlyGet Request Status
Check the state of a queued fal request. Returns status (IN_QUEUE, IN_PROGRESS or COMPLETED), request_id, queue_position while queued, and optional runner logs and metrics. Use after fal_submit_request, passing only the owner/alias part of its endpoint_id as app_id; once the status is COMPLETED call fal_get_request_result.
Inputs
app_idstringrequired- Application ID: only the first two segments (owner/alias) of the endpoint ID the request was submitted to. For fal-ai/flux/dev use fal-ai/flux.
request_idstringrequired- Request ID returned when the request was submitted to the queue.
logsinteger- Set to 1 to include runner logs in the response, 0 to omit them.one of
01
fal_get_workflowGet one fal workflow including its full definition.Read-onlyGet Workflow
Get one fal workflow including its full definition. Returns the workflow with name, title, user_nickname, is_public, created_at and contents (nodes, schema, output). Find names with fal_list_workflows.
Inputs
usernamestringrequired- Username (nickname) of the workflow owner.
workflow_namestringrequired- Workflow name (letters, digits, underscores and hyphens).
fal_list_asset_collectionsList collections in the fal Assets library.Read-onlyList Asset Collections
List collections in the fal Assets library. Returns collections with id, type, name, icon, color and parent_collection_id. Use fal_get_asset_collection for one collection.
Inputs
limitinteger- Maximum number of collections to return (1-100, default 50).
offsetinteger- Number of collections to skip, for paging. Defaults to 0.
fal_list_billing_eventsList individual billing events for fal requests.Read-onlyList Billing Events
List individual billing events for fal requests. Returns events with request_id, endpoint_id, timestamp, quantity, unit and cost breakdown, plus next_cursor. Needs an API key with billing permission (BILLING or FULL preset). Use fal_get_model_usage for aggregated usage.
Inputs
api_key_idstring- Filter by API key ID(s), comma-separated.
cursorstring- Pagination cursor from the previous response's next_cursor. Keep all other filters unchanged while paging.
endstring- End of the time range (exclusive), as an ISO 8601 date or datetime. Defaults to now.
endpoint_idstring- Filter by one or more endpoint IDs, comma-separated (up to 50). Example: fal-ai/flux/dev,fal-ai/flux/schnell.
limitinteger- Maximum number of items to return per page.
login_usernamestring- Filter by team member login username(s), comma-separated.
request_idstring- Filter by request ID(s), comma-separated.
startstring- Start of the time range, as an ISO 8601 date or datetime. Defaults to 24 hours ago.
fal_list_requests_by_endpointList past requests made to one or more fal endpoints.Read-onlyList Requests by Endpoint
List past requests made to one or more fal endpoints. Returns items with request_id, endpoint_id, timestamps, HTTP status and duration, plus next_cursor. Use to audit or debug runs; use fal_search_requests for semantic search of generated content.
Inputs
endpoint_idstringrequired- Endpoint ID(s) to query, comma-separated (up to 50). Example: fal-ai/flux/dev,fal-ai/flux/schnell.
cursorstring- Pagination cursor from the previous response's next_cursor. Keep all other filters unchanged while paging.
endstring- End of the time range (exclusive), as an ISO 8601 date or datetime. Defaults to now.
limitinteger- Maximum number of requests to return (1-100, default 50).
request_idstring- Return only the request with this UUID.
sort_bystring- Sort field: ended_at (default) or duration.one of
ended_atduration startstring- Start of the time range, as an ISO 8601 date or datetime. Defaults to the last 24 hours.
statusstring- Filter by request outcome.one of
successerroruser_error
fal_list_serverless_appsList fal Serverless apps owned by the account.Read-onlyList Serverless Apps
List fal Serverless apps owned by the account. Returns apps with endpoint_id (owner/name), environment, machine_type, auth_mode and concurrency settings. Use an app's endpoint_id with the queue, analytics and request tools.
Inputs
environmentstring- Filter by environment name.
expandstring- Extra fields to include, comma-separated.
searchstring- Filter by app name text.
fal_list_workflowsList workflows owned by the authenticated fal user.Read-onlyList Workflows
List workflows owned by the authenticated fal user. Returns workflows with name, title, user_nickname, tags and the endpoint_ids they use, plus next_cursor. Use fal_get_workflow to read a workflow definition.
Inputs
cursorstring- Pagination cursor from the previous response's next_cursor. Keep all other filters unchanged while paging.
limitinteger- Maximum number of items to return per page.
searchstring- Search by workflow name or title.
used_endpoint_idsstring- Only workflows that use these endpoint ID(s), comma-separated.
fal_search_modelsList or search fal model endpoints, or look up specific endpoints by ID.Read-onlySearch Models
List or search fal model endpoints, or look up specific endpoints by ID. Returns models with endpoint_id and metadata such as display name, category, description and status. Use to find an endpoint_id before calling fal_submit_request; use fal_get_model_pricing for prices.
Inputs
categorystring- Filter by category, for example text-to-image, image-to-video or training.
cursorstring- Pagination cursor from the previous response's next_cursor. Keep all other filters unchanged while paging.
endpoint_idstring- Look up specific endpoint ID(s), comma-separated (up to 50). Example: fal-ai/flux/dev.
expandstring- Extra fields to include, comma-separated: openapi-3.0 (full OpenAPI schema of the model) or enterprise_status.
limitinteger- Maximum number of items to return per page.
qstring- Free-text search over model name, description and category.
sortstring- Result ordering: relevant (default) or recent.one of
relevantrecent statusstring- Filter by model status. Omit to include all.one of
activedeprecated
fal_search_requestsSearch or browse your fal request history, including semantic search by text, image or video.Read-onlySearch Requests
Search or browse your fal request history, including semantic search by text, image or video. Returns results with request_id, endpoint_id, timestamps and status, plus next_cursor. Use to find earlier generations; use fal_list_requests_by_endpoint to filter by endpoint and time.
Inputs
cursorstring- Pagination cursor from the previous response's next_cursor. Keep all other filters unchanged while paging.
endpoint_idstring- Restrict to one or more endpoint IDs, comma-separated.
exclude_api_requestsboolean- Exclude requests made through the API.
image_urlstring- Image URL for image-to-image similarity search.
limitinteger- Maximum number of items to return per page.
min_similaritynumber- Minimum similarity score between 0 and 1 for semantic search.
only_api_requestsboolean- Return only requests made through the API.
querystring- Text query for semantic search over generated content.
video_urlstring- Video URL for video similarity search.
fal_sign_file_urlCreate a temporary signed URL for a fal CDN file, even if its access is restricted.Read-onlySign File URL
Create a temporary signed URL for a fal CDN file, even if its access is restricted. This creates nothing permanent. Returns signed_url. Use to share an access-restricted generated file.
Inputs
expiration_secondsintegerrequired- How long the signed URL stays valid, in seconds (1 to 604800).
urlstringrequired- URL of the fal CDN file to sign.
fal_add_asset_to_collectionAdd an asset to a manual fal Assets collection.WriteAdd Asset to Collection
Add an asset to a manual fal Assets collection. Returns success true when added. Provide exactly one of asset_id, request_id or vector_id.
- Idempotent
Inputs
collection_idstringrequired- ID of the collection to add to.
asset_idstring- Asset ID to add.
request_idstring- Request ID whose output to add as an asset.
vector_idstring- Vector ID of the asset to add.
fal_cancel_requestCancel a queued or running fal request.WriteCancel Request
Cancel a queued or running fal request. Returns a cancellation status such as CANCELLATION_REQUESTED; a request already mid-processing may still complete. Use to stop a request submitted with fal_submit_request; app_id is the owner/alias part of its endpoint_id.
Inputs
app_idstringrequired- Application ID: only the first two segments (owner/alias) of the endpoint ID the request was submitted to. For fal-ai/flux/dev use fal-ai/flux.
request_idstringrequired- Request ID returned when the request was submitted to the queue.
fal_create_asset_collectionCreate a manual collection in the fal Assets library.WriteCreate Asset Collection
Create a manual collection in the fal Assets library. Returns the created collection with id, name and type. Use fal_add_asset_to_collection afterwards to fill it.
Inputs
namestringrequired- Collection name (1-255 characters).
colorstring- Optional color for the collection.
iconstring- Optional icon for the collection.
parent_collection_idstring- Optional ID of a parent collection to nest this one under.
fal_run_modelRun a fal model with a direct blocking call and wait for the result, with no queue.WriteRun Model Synchronously
Run a fal model with a direct blocking call and wait for the result, with no queue. Returns the model-specific output JSON, for example images, video or audio objects with media URLs. Use for fast models; use fal_submit_request for long-running generation.
Inputs
endpoint_idstringrequired- Endpoint ID of the model or app, in the form owner/app or owner/app/path. Example: fal-ai/flux/dev.
inputobjectrequired- JSON object with the model's input arguments, exactly as documented on the model's API page. Example: {"prompt": "a sunset over mountains"}.
fal_submit_requestSubmit a generation request to a fal model or app through the durable queue and return immediately.WriteSubmit Request
Submit a generation request to a fal model or app through the durable queue and return immediately. Returns request_id, status_url, response_url, cancel_url and queue_position. Use fal_get_request_status to poll and fal_get_request_result to fetch the output. Use fal_run_model for a short blocking call instead.
Inputs
endpoint_idstringrequired- Endpoint ID of the model or app, in the form owner/app or owner/app/path. Example: fal-ai/flux/dev.
inputobjectrequired- JSON object with the model's input arguments, exactly as documented on the model's API page. Example: {"prompt": "a sunset over mountains"}.
prioritystring- Queue priority for this request. Defaults to normal.one of
lownormalhighdefaultnormal webhook_urlstring- Optional HTTPS URL that fal calls with the result when the request completes.
fal_update_asset_collectionUpdate the name, icon, color or cover image of a fal Assets collection.WriteUpdate Asset Collection
Update the name, icon, color or cover image of a fal Assets collection. Returns the updated collection. Only the fields you provide change.
- Idempotent
Inputs
collection_idstringrequired- ID of the collection to update.
colorstring- New color for the collection.
cover_image_urlstring- New cover image URL.
iconstring- New icon for the collection.
namestring- New collection name (1-255 characters).
fal_upload_assetAdd a media file to the fal Assets library from a public URL.WriteUpload Asset from URL
Add a media file to the fal Assets library from a public URL. Returns the created asset with asset_id, url, type and created_at. Use fal_browse_assets to find it afterwards.
Inputs
typestringrequired- Media type of the file.one of
imagevideoaudio3d urlstringrequired- Public URL of the file to import.
collection_idstring- Optional collection to place the asset in.
favoriteboolean- Mark the asset as a favorite. Defaults to false.default
false promptstring- Optional prompt or description to store with the asset (up to 2000 characters).
fal_delete_request_payloadsPermanently delete the stored input and output payloads and output CDN files of one fal request.DestructiveDelete Request Payloads
Permanently delete the stored input and output payloads and output CDN files of one fal request. Returns cdn_delete_results listing each deleted link and any error. Irreversible; needs an API key with the FULL preset.
- Idempotent
Inputs
request_idstringrequired- UUID of the request whose payloads to delete. Irreversible.
No tools match.
