Skip to main content
This guide is for teams that run production workloads on fal and want to move some or all of them to Runpod. Calls to fal’s hosted Model APIs map to Runpod Public Endpoints, 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.
A coding agent can do most of this migration for you. See Migrate with a coding agent.

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 an input 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 fal CLI 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 with fal account set TEAM_NAME and repeat.
fal Compute instances don’t appear in the app list. List them in the Compute dashboard or through the Platform API.
For each 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.
Write down every model ID you call (strings such as 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.
On macOS you can also install 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 in https://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.
A matching name doesn’t mean matching output. The two platforms can run different versions, tiers, default steps, and guidance values of the same model family, and fal lists both pro and standard tiers for some Kling endpoints. Run your own prompts through both before you switch traffic, and compare parameters on each Runpod model page.
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 with runpodctl 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 typical fal.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
Callers get {"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

Use @app.queue when callers use subscribe, submit, or webhooks today. It creates a queue-based endpoint with /run, /runsync, and /status.
main.py
The function’s keyword arguments become the job 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.
Both versions return the image as base64 because nothing on Runpod uploads your outputs for you. Job requests and results are JSON with a size limit (10 MB for /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 (a ContainerImage 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
The return value keeps fal’s 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
If you used 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.
For a private registry, save credentials with 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.
Without a cached model, this handler downloads the SDXL weights on every cold start. Add a cached model in Step 6, which the handler reads through cache_dir, bake the weights into the image, or use a network volume. See Step 5.

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 returns not allowed for QB API. To move a @fal.realtime or is_websocket=True endpoint:
  1. Serve the WebSocket route from your own HTTP server (for example FastAPI’s @app.websocket("/ws")) alongside GET /ping, in a custom image deployed as a load-balancing endpoint.
  2. Replace fal’s realtime protocol with your own messages. @fal.realtime uses fal’s binary msgpack protocol and the fal_client.realtime() and fal.realtime.connect() clients. On Runpod the client is any WebSocket library, and the frames are whatever your server sends.
  3. Connect to wss://ENDPOINT_ID.api.runpod.ai/ws and send Authorization: Bearer YOUR_API_KEY as a header on the connection request.
  4. 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
The load-balancing limits apply: a request waits up to 2 minutes for a worker, processing is limited to 5.5 minutes per request, and payloads are limited to 30 MB. Test how long your sessions stay open before you rely on them, and keep at least one active worker for interactive use so the first connection doesn’t wait on a cold start. A browser can’t hold your API key safely, so keep the proxy pattern you used with fal (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 a fal.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.
Download your files from fal to a machine with enough disk, then copy them to the volume through the S3-compatible API. Create an S3 API key in the console first and configure it with aws configure. The bucket name is the network volume ID.
The S3 API is available in the data centers listed on the S3 API page. For large transfers, or a data center that isn’t listed, start a Pod with the volume attached and pull the files from their original source there (for example with 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.
Loading weights directly from the network mount on every cold start is slower than loading from local disk. The volume cache pattern copies them to the worker’s disk first.
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.
Scaling lives in code on 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.
With 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.
For the 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, the input 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.
Before, with fal-client:
fal_call.py
After, with plain HTTP:
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.
Use /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 a fal_webhook query parameter (or webhook_url in the clients). Runpod takes a top-level webhook field in the body.
Update your receiver for three differences:
  • Payload. fal posts {"request_id", "status": "OK" or "ERROR", "payload"}. Runpod posts the job object, the same shape /status returns: id, status (COMPLETED, FAILED, and so on), and output.
  • Retries. fal retries with backoff for up to about an hour. Runpod expects a 200 and retries up to 2 more times with a 10-second delay, so make the receiver fast and reliable, and fall back to /status/JOB_ID for jobs you haven’t heard about. Results are only retained for 30 minutes after completion.
  • Verification. If you verify fal’s X-Fal-Webhook-Signature today, replace it with a secret token in the webhook URL path or query, and confirm the job by calling /status/JOB_ID with 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.
Install it with 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 deployed fal.App is called by its OWNER/APP_NAME ID. A Runpod endpoint is called by its endpoint ID.
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 the fal 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 /data files and any CDN outputs you need before you run these.
Delete fal Compute instances in the Compute dashboard or with 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.
Then give the agent this prompt from the root of your repository:

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.
Last modified on November 14, 2026