setup / fal-api-key
How to set up your Universal Modder fal API key
Quick answer
Set up a fal API key to enable AI-generated 2D sprites, textures, 3D meshes, and game audio inside universal-modder in about five minutes. The universal-modder plugin is free; fal asset generation is a paid service charged per generation, with 3D models and video being the most expensive tasks.
Prerequisites
- A legally owned single-player PC game within the usage boundary below.
- An active account on fal (https://fal.ai).
- Billing credit added to your fal account balance.
- A terminal or shell session to set the FAL_KEY environment variable.
- Any supported AI agent or the um CLI installed on your machine.
Steps: how to set up your Universal Modder fal API key
-
Create a fal account and add funds
What to do
Visit fal.ai, register an account, and add funds to your account balance. The service is paid: every generation is charged against your balance, and 3D models and video are among the most expensive tasks.
Command
Web browser:
Command https://fal.aiWhat you should see
Your fal account profile displays an active credit balance after depositing funds.
If something goes wrong
You can still use universal-modder plugins without a fal key for engine reconnaissance, reverse engineering, save backups, and code editing; the agent skips visual and audio generation if no key is configured.
-
Generate and save your API key
What to do
Navigate to the API keys page on the fal dashboard. Generate a new key and copy it immediately to a password manager or secure note. The key is only shown once, so save it immediately.
Command
Web browser:
Command https://fal.ai/dashboard/keysWhat you should see
fal displays your newly generated secret key once in the dashboard modal.
If something goes wrong
If you navigate away or close the dialog before copying the key, revoke it and generate a new key, as fal will not display the secret key again.
-
Set the FAL_KEY environment variable
What to do
Pass the key to your operating system through the
FAL_KEYenvironment variable. You can also place the key in a .env file inside the project folder using FAL_KEY=your_key. The um utility can read it from there, but the fal MCP server in Claude Code reads the key only from the environment variable.Command
Windows terminal:
Command setx FAL_KEY your_keymacOS and Linux terminal (add to
~/.bashrcor~/.zshrc):Command export FAL_KEY=your_keyWhat you should see
The variable is registered in your operating system environment.
If something goes wrong
On Windows, restart your terminal or editor after running
setxso processes receive the updated variable. On macOS or Linux, reload your shell profile or restart your terminal. -
Check cost expectations and generation prices
What to do
Review cost expectations before requesting heavy asset generation. 2D sprites with transparent backgrounds and textures cost less, whereas 3D models, rigs, and showcase video edits consume significantly more billing balance. Before expensive generations, ask for the price. The agent can check it with
um fal price. Exact per-call dollar rates vary by model:Command
Command um fal priceWhat you should see
The command reports estimated pricing for the targeted model or task.
If something goes wrong
If
umis not on your PATH, install it usinguv tool install git+https://github.com/rehan-remade/universal-modderor run with uv:uvx --from git+https://github.com/rehan-remade/universal-modder um fal price.
Verify it worked
- Check that
echo $FAL_KEY(orecho %FAL_KEY%on Windows) prints your configured key. - Verify that your fal dashboard balance shows active credits.
- Run
um fal priceto verify that the tool recognizes your API key. - Test generating a small sprite with the agent before initiating large 3D or video tasks.
- Verify the generated asset in your mod folder.
FAQ
Can I use Universal Modder without a fal API key?
Yes. The plugin still works without an API key, but the agent will not be able to generate sprites, models, or sounds on its own. Code modding, engine discovery, and save backups remain fully functional.
Why does Claude Code fail to connect to fal even if I put FAL_KEY in .env?
Claude Code’s fal MCP server reads the key only from the environment variable. Putting FAL_KEY=your_key in .env allows the um CLI to read it, but does not configure Claude Code’s MCP connection. You must export FAL_KEY in your shell or run setx FAL_KEY your_key on Windows.
Which fal asset generation tasks are the most expensive?
The service is paid: every generation is charged against your balance, and 3D models and video are among the most expensive tasks. Use um fal price to inspect generation costs before creating complex assets.
How do I check if my fal API key has sufficient balance?
Log in to the fal.ai dashboard and check your usage tab, or run um fal price in your terminal to see cost estimations for sprite, 3D mesh, and audio operations before initiating a large batch generation.
Why do asset generations timeout or fail on slow internet connections?
3D remeshing and high-resolution video generations require transferring multi-megabyte payloads. If your connection is unstable, try starting with lower-resolution 2D sprite cutout jobs first to verify that your API key authentication works reliably.