fal.App deployments on fal Serverless map to Runpod Serverless endpoints, and fal Compute instances map to Pods and Instant Clusters. By the end, each workload runs on Runpod, your client code calls Runpod, and the fal resources that were billing are shut down.
How fal maps to Runpod
What’s different
What works differently
The request body is wrapped. fal takes model parameters at the top level of the JSON body. Runpod takes them inside aninput object, and options such as webhook and policy sit beside input.
The result arrives with the status. fal has separate status and result URLs. Runpod’s /status/JOB_ID returns the status and, once the job completes, the output.
Failures have their own statuses. fal reports IN_QUEUE, IN_PROGRESS, and COMPLETED, and a failed request is COMPLETED with an error field. Runpod adds FAILED, CANCELLED, and TIMED_OUT. Update any code that treats COMPLETED as the only terminal state.
Results don’t stay around as long. fal stores request payloads for 90 days by default. Runpod keeps the result of a /run job for 30 minutes after completion and a /runsync result for 1 minute. Fetch results promptly or use a webhook, and store what you need.
Output URLs expire. Public Endpoint output URLs (image_url, video_url, audio_url, result) expire after 7 days. If you relied on fal CDN URLs as long-lived links, copy outputs to your own storage.
Secrets are opt-in per endpoint. By default fal injects every secret in the environment into a runner. On Runpod you map each secret into an environment variable yourself, with runpod.Secret("NAME") in the SDK or {{ RUNPOD_SECRET_NAME }} in a template or endpoint.
Model weights aren’t cached for you. fal sets HF_HOME to /data/.cache/huggingface on every runner. On Runpod, weights download to the worker’s container disk on each cold start unless you use cached models, a volume, or bake them into the image.
Storage is attached, not ambient. /data is mounted on every fal runner in your account. A Runpod network volume is created with a size, lives in one data center, and is attached to specific endpoints or Pods. Attaching one limits those workers to that data center.
Auth is always a Runpod API key. fal apps can be private, public, or shared. Runpod Serverless endpoints check a Runpod API key on every request. For unauthenticated access, put your own backend in front of the endpoint.
Idle timeout defaults are shorter. fal’s keep_alive defaults to 60 seconds. The Runpod SDK’s idle_timeout also defaults to 60, but the console default is 5 seconds and the REST v2 default is 10. Set it explicitly.
Execution timeouts are shorter by default. fal’s request_timeout defaults to 3600 seconds. Runpod’s execution timeout defaults to 600 seconds in the console and 300000 ms in REST v2. The SDK’s execution_timeout_ms defaults to no limit.
You build images yourself for the custom-image path. fal deploy builds containers remotely. With the Runpod SDK, rp flash deploy also packages your code without Docker. With a custom worker, you build and push a linux/amd64 image, or let the GitHub integration build it.
What has no direct equivalent
Going the other way, some things exist on Runpod that you may not have used on fal: text models with an OpenAI-compatible route on Public Endpoints,
@app.task for run-to-completion jobs on a dedicated Pod, per-second Pod billing, and Community Cloud or Secure Cloud placement for Pods.
Requirements
- A Runpod account with credits.
- A Runpod API key.
- Access to your fal account or team, with the
falCLI installed and logged in (fal auth login). - Python 3.10 to 3.14 for the Runpod SDK.
- Docker, if you’ll deploy a custom image.
- An S3-compatible bucket, if your app returns files and you don’t want to return base64.
Step 1: Take inventory of what you run on fal
List everything in each fal account and team before you move anything. If you use teams, switch withfal account set TEAM_NAME and repeat.
fal.App, record these values from the source file or pyproject.toml: machine_type, num_gpus, min_concurrency, max_concurrency, keep_alive, max_multiplexing, request_timeout, startup_timeout, regions, requirements or the ContainerImage Dockerfile, the secrets it reads, every /data path it touches, and every @fal.endpoint and @fal.realtime path. Scaling values changed with fal apps scale override the code, so trust fal apps list --json over the source for those.
Then find the code that calls fal. This command finds SDK imports, CLI usage, hostnames, and environment variables.
fal-ai/flux/dev and workflows/OWNER/NAME), whether each call uses subscribe, submit, run, stream, or realtime, and whether it uses webhooks, fal_client.upload_file, or stored fal CDN URLs.
Step 2: Set up Runpod
Create an API key in the console, then install the tools you need.runpodctl with brew install runpod/runpodctl/runpodctl. For agent-driven work, connect the Runpod MCP server.
Step 3: Choose where each workload lands
Model map
These fal model IDs have a counterpart in the Runpod model reference. The Runpod endpoint ID is the path segment inhttps://api.runpod.ai/v2/ENDPOINT_ID/runsync. Both catalogs change, so check the model reference and the Hub playground before you commit to a mapping.
Runpod also hosts text models (for example
qwen3-32b-awq) with an OpenAI-compatible route at https://api.runpod.ai/v2/ENDPOINT_ID/openai/v1. For fal models that aren’t in the table, such as models from the FLUX Pro, Veo, Ideogram, and ElevenLabs families, or other Kling and Sora variants, check the model reference for a current listing, then plan to keep the call on a provider that hosts the model or self-host an open alternative on Serverless.
GPU map
fal machine types name a GPU class. Runpod Serverless selects hardware by GPU pool, and Pods select by GPU type. Pick by the VRAM your model needs, then check live stock withrunpodctl gpu list or GET /v2/catalog/gpus, because availability varies by data center.
fal’s
GPU-A100 is the 40 GB card. Runpod’s A100 pool is the 80 GB card, so a workload sized for 40 GB also fits the 48 GB pool. A list such as machine_type = ["GPU-H100", "GPU-A100"] maps to a list of pools, for example gpu=["H100", "A100"] in the SDK. See GPU types for every type and pool.
Step 4: Move your images and code
If you only call hosted models, skip to Step 7.The fal app you’re starting from
This is the shape of a typicalfal.App: setup() loads the model once per runner, and one endpoint takes a pydantic input and returns an Image that fal uploads to its CDN.
fal_app.py
{"image": {"url": "https://...fal.media/..."}}. On Runpod you choose between two paths: the Runpod SDK, which is closest to the fal workflow, or a custom image with a handler, which gives you full control of the container.
Option A: The Runpod SDK
- Queue endpoint (@app.queue)
- HTTP service (@app.api)
Use The function’s keyword arguments become the job
@app.queue when callers use subscribe, submit, or webhooks today. It creates a queue-based endpoint with /run, /runsync, and /status.main.py
input, so a caller sends {"input": {"prompt": "..."}}. The pydantic Input model becomes a typed function signature. torch is already installed on the built-in GPU images, so it isn’t listed in dependencies. Packages are imported inside the function because top-level imports run on your machine./run, 20 MB for /runsync), so return base64 only for small outputs. For video, audio, or large images, upload to your own bucket and return the URL, as Option B does.
model=sdxl replaces fal’s automatic Hugging Face cache on /data. Runpod stages the weights on the host before the worker starts, and libraries that use the standard Hugging Face cache find them. Gated models need an HF_TOKEN on the same resource, passed as env={"HF_TOKEN": runpod.Secret("hf-token")}.
Option B: A custom image with a handler
Use this path when you already have a Dockerfile (aContainerImage on fal), need system packages or a pinned CUDA stack, or want the response to carry a file URL.
The handler loads the model at module level, which runs once per worker, and uses the rp_upload helper to put the image in your S3-compatible bucket.
handler.py
image.url shape, so callers change result["image"]["url"] to result["output"]["image"]["url"]. Input validation that pydantic did on fal is now your code. Returning a dictionary with an error key marks the job as failed. rp_upload.upload_image returns a presigned URL that’s valid for 7 days, so generate your own URL or copy the file if callers need a longer-lived link.
The Dockerfile installs the handler’s dependencies on a CUDA base image and starts the handler.
Dockerfile
ContainerImage.from_dockerfile_str on fal, start from that Dockerfile and add three things back: pip install runpod, a COPY of your handler, and a CMD that runs it. Build for linux/amd64 and push to a registry Runpod can pull from.
runpodctl registry create --name "docker-hub" --username "DOCKER_USERNAME" and pass the returned ID as --registry-auth-id when you create the template. This replaces the registries parameter on fal’s ContainerImage.
Existing HTTP servers
If your fal app runs in direct server mode (exposed_port in pyproject.toml), the same image runs on a Runpod load-balancing endpoint. Your server must answer GET /ping with 200 when it’s ready (204 while initializing) and listen on the port in the PORT environment variable, which defaults to 80. If you set PORT, set PORT_HEALTH to the same value and expose that port on the endpoint. To use a different health path, set HEALTH_CHECK_PATH.
Streaming endpoints
A fal endpoint at/stream that returns a StreamingResponse has two Runpod forms. On a queue-based endpoint, write a generator handler (or a generator function under @app.queue) that yields chunks, and have clients read them from /stream/JOB_ID. On a load-balancing endpoint, keep your FastAPI StreamingResponse as it is. See handler functions for streaming handlers and progress updates.
Realtime and WebSocket inference
Runpod supports WebSocket connections on load-balancing endpoints. Queue-based endpoints don’t accept custom routes, so a WebSocket route there returnsnot allowed for QB API. To move a @fal.realtime or is_websocket=True endpoint:
- Serve the WebSocket route from your own HTTP server (for example FastAPI’s
@app.websocket("/ws")) alongsideGET /ping, in a custom image deployed as a load-balancing endpoint. - Replace fal’s realtime protocol with your own messages.
@fal.realtimeuses fal’s binary msgpack protocol and thefal_client.realtime()andfal.realtime.connect()clients. On Runpod the client is any WebSocket library, and the frames are whatever your server sends. - Connect to
wss://ENDPOINT_ID.api.runpod.ai/wsand sendAuthorization: Bearer YOUR_API_KEYas a header on the connection request. - Raise the client’s connection timeout. The default of about 5 seconds isn’t enough when a worker has to start. The Runpod docs recommend
open_timeout=60.
client.py
proxyUrl) and connect from your backend. See Build a load-balancing worker and the worker-lb-websocket example.
fal’s hosted realtime models (fal-ai/fast-lcm-diffusion, fal-ai/fast-turbo-diffusion) aren’t in the Runpod model reference. To keep that feature, self-host the model behind a WebSocket route.
ComfyUI workflows
fal’s ComfyUI pattern runs the ComfyUI server in a custom container inside afal.App and posts an API-format workflow to it. On Runpod, the ComfyUI worker does the same job as a ready-made queue-based endpoint. Deploy it from the Hub listing, or use one of the runpod/worker-comfyui images (-base, -flux1-schnell, -flux1-dev, -sdxl, -sd3).
Your exported workflow_api.json goes in the request as {"input": {"workflow": { ... }}}, and the result returns images as base64 in output.images[0].data. The Hub listing ships with FLUX.1-dev-fp8 and works only with that model. For other checkpoints, LoRAs, or custom nodes, build a customized image by following the worker’s customization guide, the same way you packaged nodes and models into the fal container.
Runtime environment variables
Code that reads fal’s injected variables needs new names. See the environment variable map.FAL_KEY deserves attention: fal injects it so an app can call other fal models, and those calls are billed to you. If your worker calls Runpod Public Endpoints or other endpoints, pass a Runpod API key to it as a secret.
Step 5: Move your data and models
Decide what each/data path was for, because the Runpod target differs.
Create the network volume in the data center where you want workers to run. Check GPU stock there first, because an attached volume keeps the endpoint in that data center.
aws configure. The bucket name is the network volume ID.
hf download or wget), which avoids routing everything through your machine. aws s3 sync works for basic cases but can have trouble with very large file counts.
Files on the fal CDN (generated outputs and fal_client.upload_file uploads) are public URLs with a retention you may have configured. If your database stores fal.media URLs, download those files to your own storage before you close the account.
Recreate secrets by name. Values can’t be read back from fal, so take them from your secret manager.
rp secret add prompts for the value, which keeps it out of your shell history. Secret names that start with RUNPOD are rejected.
Step 6: Deploy on Runpod
Public Endpoints
There’s nothing to deploy. Public Endpoints are live for every account, and your API key works on all of them. Go to Step 7.Serverless with the Runpod SDK
rp flash dev plays the role of fal run: it creates temporary endpoints, runs your @runpod.local_entrypoint, streams worker logs, and deletes the endpoints when you exit. rp flash deploy plays the role of fal deploy.
- fal
- Runpod
workers=(1, 10), idle_timeout=300), so change the decorator and deploy again. rp flash deploy prints a link to each endpoint. To change scaling on a live endpoint without a deploy, use runpodctl serverless update ENDPOINT_ID --workers-min 1 --workers-max 10 --idle-timeout 300.
Serverless with a custom image
Create a Serverless template for the image, then an endpoint from the template. This is the queue-based deployment of the handler from Option B.--gpu-id takes a pool ID or a GPU type ID. --model-reference attaches a cached model at /runpod-volume/huggingface-cache/hub/. A custom handler has to load from that path, which is what cache_dir does in the Option B handler. To attach the network volume from Step 5, add --network-volume-id NETWORK_VOLUME_ID. Each Serverless template binds to one endpoint, so create a template per endpoint. Check runpodctl serverless create --help for the full flag list.
The same endpoint through REST API v2, without a separate template:
type and scaling are required in REST v2, and its defaults differ from the console: FlashBoot is OFF and the idle timeout is 10 seconds unless you set them. In the console, the same flow is Serverless, then New Endpoint.
Load-balancing endpoint (HTTP servers and WebSockets)
Create a load-balancing endpoint through REST API v2 with"type": "LOAD_BALANCER" and a request-count scaler. Expose the port your server binds and set PORT and PORT_HEALTH to match it.
workers.min at 1, one worker bills continuously. Wait for GET https://ENDPOINT_ID.api.runpod.ai/ping to return 200 before you send traffic. If the ports don’t match, the worker shows as running but never becomes healthy.
Pods and Instant Clusters (fal Compute)
A fal Compute instance is a dedicated machine you SSH into. A Pod is a container with SSH, so install your stack in the image or on a volume rather than with a VM-level setup, and note that Pods don’t run Docker Compose.8xH100-SXM shape, set --gpu-count 8 if a host with eight GPUs is in stock in your data center. For multi-node training that used InfiniBand between 8-GPU instances in one fal sector, deploy an Instant Cluster, which provides high-speed networking between nodes with Slurm, PyTorch, or Ray setups. GPU and cluster availability varies by data center and over time, so check stock before you plan a cutover date, and add your SSH key with rp ssh add or in the console. Check runpodctl pod create --help for the full flag list.
Step 7: Update the code that calls fal
Hosted model calls
The examples below call FLUX.1 dev. Four things change: the URL, the auth header, theinput wrapper, and the parameter and output names.
For FLUX.1 dev, the parameters map as follows. Other models differ, so read the Runpod model page for each one.
Across models, the common renames are
image_url to image, image_urls to images, and audio_url to audio. Sizes are often a size string such as 1024*1024 or 1280*720. Outputs are output.image_url, output.video_url, output.audio_url, or output.result, depending on the model, plus output.cost.
- Python
- JavaScript
- cURL
Before, with After, with plain HTTP:
fal-client:fal_call.py
runpod_call.py
/runsync returns the finished job when it completes within the wait window. If it doesn’t, the response carries the job id and a non-terminal status, and wait_for picks it up from /status. The polling interval grows instead of running in a tight loop, which keeps you within the endpoint’s rate limits./run with polling or a webhook for video models, which can run longer than the /runsync wait window.
Input files
fal_client.upload_file("image.png") and fal.storage.upload(file) return a fal CDN URL that you pass to a model. Runpod Public Endpoint model pages take input media as URLs (for example input.image on WAN 2.5 and input.images on Nano Banana 2 Edit). Upload inputs to your own bucket and pass a URL the endpoint can fetch, such as a presigned URL.
Webhooks
fal takes the webhook as afal_webhook query parameter (or webhook_url in the clients). Runpod takes a top-level webhook field in the body.
- fal
- Runpod
- Payload. fal posts
{"request_id", "status": "OK" or "ERROR", "payload"}. Runpod posts the job object, the same shape/statusreturns:id,status(COMPLETED,FAILED, and so on), andoutput. - Retries. fal retries with backoff for up to about an hour. Runpod expects a
200and retries up to 2 more times with a 10-second delay, so make the receiver fast and reliable, and fall back to/status/JOB_IDfor jobs you haven’t heard about. Results are only retained for 30 minutes after completion. - Verification. If you verify fal’s
X-Fal-Webhook-Signaturetoday, replace it with a secret token in the webhook URL path or query, and confirm the job by calling/status/JOB_IDwith your API key.
Vercel AI SDK
If you call fal through@ai-sdk/fal, switch to @runpod/ai-sdk-provider. The provider reads RUNPOD_API_KEY in place of FAL_API_KEY or FAL_KEY.
- fal
- Runpod
npm install @runpod/ai-sdk-provider ai. Model-specific options move from the fal key to the runpod key in providerOptions, with Runpod’s parameter names. The provider’s model IDs for some image and video models differ from the REST endpoint IDs (for example alibaba/wan-2.6-t2v), so copy them from the supported models tables. The Runpod page imports experimental_generateImage. Use whichever export your installed ai version provides. The provider also accepts your own Serverless endpoint ID as a model identifier.
Calls to your own app
A deployedfal.App is called by its OWNER/APP_NAME ID. A Runpod endpoint is called by its endpoint ID.
- fal
- Runpod
runpod.Endpoint wraps the input in {"input": ...} for you and reads the API key from rp login, RUNPOD_API_KEY, or runpod.api_key. To send a webhook, post to /run directly with a top-level webhook field as shown above. From another SDK codebase, you can also call a deployed app by name with runpod.Queue(app="my-demo-app", name="generate") or runpod.Api(app="my-demo-app", name="MyApp").
Control-plane automation
Scripts and CI jobs that run thefal CLI or call https://api.fal.ai/v1 move to runpodctl, the rp CLI, or REST API v2. See the CLI command map and API map. In CI, replace the fal key with a RUNPOD_API_KEY secret and run rp flash deploy --env production in place of fal deploy --env production.
Step 8: Verify, cut over, and shut down
1
Send a real request from outside
Call each Runpod endpoint from the environment your production clients run in, not from the machine you deployed from. For a queue-based endpoint:Open the returned URL or decode the base64 and check the output is what you expect.
2
Compare outputs and latency
Run the same prompts and seeds through fal and Runpod. Compare output quality, then the timing fields:
delayTime (queue wait, including any cold start) and executionTime on Runpod against metrics.inference_time and your measured wall-clock time on fal. Measure a cold request and a warm one separately.3
Run both in parallel
Put the provider behind a flag in your client so a request can go to either. Send a small share of traffic to Runpod, watch the endpoint’s Metrics and Logs tabs, and check that webhooks arrive and that your code handles
FAILED and TIMED_OUT.4
Shift traffic
Raise the share in stages. Before each stage, confirm your max workers and scaler settings can absorb the new volume. Keep fal deployed until you’ve gone a full traffic cycle on Runpod.
5
Stop billing on fal
Scale warm runners to zero first, then delete what you no longer need. Deleting is permanent, so export Delete fal Compute instances in the Compute dashboard or with
/data files and any CDN outputs you need before you run these.DELETE https://api.fal.ai/v1/compute/instances/INSTANCE_ID. They bill per hour while they exist. Model API usage stops when your code stops calling it.6
Set a cost guard on Runpod
Keep
workers minimums at 0 for endpoints that don’t need warm capacity, set a max worker count you’re comfortable paying for, and set an execution timeout so a stuck job can’t run indefinitely. Delete network volumes and stopped Pods you no longer need, because storage bills until it’s deleted. Review spend on the billing page.Reference
CLI command map
API map
Configuration field map
Environment variable map
Status map
Migrate with a coding agent
Install the Runpod plugin or skills and connect the MCP server. MCP sign-in is OAuth (“Sign in with Runpod”), so you don’t need an API key to start. See agent skills and MCP servers.- Claude Code
- Other agents
Troubleshooting
401 from every Runpod request. The client still sends Authorization: Key .... Runpod expects Authorization: Bearer YOUR_API_KEY. On WebSockets, send the header on the connection request.
The job fails validation or ignores your parameters. The body isn’t wrapped in input, or it uses fal parameter names. Send {"input": {...}} and rename parameters per the Runpod model page (image_size to width and height, guidance_scale to guidance, image_url to image).
KeyError: 'images' or undefined when reading the result. The output shape changed. Read output.image_url, output.video_url, output.audio_url, or output.result, depending on the model.
/status returns 404 or no output for a job that finished. Results are kept for 30 minutes after a /run job completes and 1 minute for /runsync, and a job’s TTL (24 hours by default) deletes it regardless of state. Fetch results sooner or use a webhook.
Code waits forever on a job that failed. A polling loop that only exits on COMPLETED never sees FAILED, CANCELLED, or TIMED_OUT. Treat all four as terminal.
Jobs end as TIMED_OUT that finished on fal. fal’s request_timeout defaults to 3600 seconds, and Runpod’s execution timeout defaults to 600 seconds in the console and 300000 ms in REST v2. Raise the endpoint’s execution timeout or set policy.executionTimeout on the request.
Every cold start downloads the model again. fal cached Hugging Face downloads on /data without configuration. On Runpod, add a cached model (model= or --model-reference), bake weights into the image, or use a network volume with the volume cache pattern.
os.getenv("HF_TOKEN") is None on the worker. Secrets aren’t injected automatically. Create the secret, then reference it with runpod.Secret("hf-token") or {{ RUNPOD_SECRET_hf-token }} in the endpoint’s environment. Values in a local .env file aren’t sent to workers.
A load-balancing worker shows as running but requests hang or return 502. The server isn’t listening where the health check looks. Bind 0.0.0.0 on PORT, set PORT_HEALTH to the same port, expose that port, and answer GET /ping with 200. An error of not allowed for QB API means the endpoint was created as queue-based.
WebSocket connections time out on connect. The client gave up while a worker was starting. Set open_timeout=60 or the equivalent in your client, and keep one active worker for interactive apps.
The job fails when the handler returns a large image or video. Job payloads are limited to 10 MB for /run and 20 MB for /runsync. Upload the file to your bucket with rp_upload and return the URL.
The image won’t start, or the worker exits immediately. Images built on Apple silicon default to arm64. Build with docker build --platform linux/amd64. If CUDA initialization fails, set a minimum CUDA version on the endpoint that matches your image.
Next steps
Public Endpoint model reference
Check current models, parameters, and pricing.
Runpod SDK overview
Define queue, API, and task resources in Python.
Endpoint settings
Tune workers, idle timeout, and autoscaling.
Load-balancing endpoints
Serve your own HTTP and WebSocket routes.