Skip to content
Universal Modder Guides

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

  1. 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.ai

    What 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.

  2. 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/keys

    What 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.

  3. Set the FAL_KEY environment variable

    What to do

    Pass the key to your operating system through the FAL_KEY environment 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_key

    macOS and Linux terminal (add to ~/.bashrc or ~/.zshrc):

    Command
    export FAL_KEY=your_key

    What 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 setx so processes receive the updated variable. On macOS or Linux, reload your shell profile or restart your terminal.

  4. 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 price

    What you should see

    The command reports estimated pricing for the targeted model or task.

    If something goes wrong

    If um is not on your PATH, install it using uv tool install git+https://github.com/rehan-remade/universal-modder or run with uv: uvx --from git+https://github.com/rehan-remade/universal-modder um fal price.

Verify it worked

  • Check that echo $FAL_KEY (or echo %FAL_KEY% on Windows) prints your configured key.
  • Verify that your fal dashboard balance shows active credits.
  • Run um fal price to 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.