fal

What it does

Provider. fal serves six tasks through fal.ai. One key, one HTTP client, one upload cache and one merged price table. It registers ("video", "fal"), ("image", "fal"), ("prompt-gen", "fal"), ("music", "fal"), ("sfx", "fal") and ("sprite", "fal") with the registry in onInit.

Every handler validates and prices a request before it reads the key, uploads or posts. A bad request bills nothing. fal registers before apimodels and ark, so it is the default provider of video, music and sprite.

Setup

Export FAL_KEY, or put it in .env.local in the working directory. The shell wins over the file. The key is read at request time: estimates, validation and models() never need it.

import { createApp } from "@moku-labs/ai";

export const app = createApp({
  pluginConfigs: {
    fal: {
      upload: "storage",
      requestLog: ".moku/fal-requests.jsonl"
    }
  }
});

Tasks it serves

Each task's request shape is on its own page. These are the fields fal reads.

version: 1
name: shots
items:
  - id: s01.key
    task: image
    provider: fal
    input: { prompt: "patisserie counter at night", model: nano-banana-pro, aspect: "9:16" }
    params: { resolution: "2K" }
  - id: s01.clip
    task: video
    provider: fal
    input:
      model: kling-3-pro
      prompt: "slow push-in, she smiles"
      image: { $ref: s01.key }
      seconds: 5
      audio: true
  - id: s01.caption
    task: prompt-gen
    provider: fal
    input: { prompt: "Caption a sunset in five words.", model: anthropic/claude-sonnet-5 }
  - id: s01.score
    task: music
    provider: fal
    input: { prompt: "tense synth pulse", model: elevenlabs-music-v2.5, lengthMs: 60000 }
  - id: coin-pickup
    task: sfx
    provider: fal
    input: { prompt: "coin pickup, bright chime", model: elevenlabs-sfx-v2, durationMs: 600 }
  - id: "btn{nine=12,12,12,12}"
    task: sprite
    provider: fal
    input: { source: { $ref: s01.key }, model: birefnet, size: { width: 128, height: 64 }, padding: 2 }

• video: model is a fal alias from the table below. image is the first frame, endImage the last frame, refs the image, audio and video references. seconds defaults to 5, aspect to 9:16, resolution to 720p (768P on MiniMax), audio to off. params is merged last into the body.
• image: model defaults to imageDefaultModel. A request with refs goes to the model's edit endpoint. params.resolution is 1K, 2K, 4K or 1080.
• prompt-gen: model is an OpenRouter id, default llmDefaultModel. params.reasoning, params.responseSchema, params.images and params.max_tokens are read; tool calling works through messages, tools and toolChoice.
• music: model is required. lengthMs must fit the model's range. chunks go out as a composition plan on ElevenLabs Music.
• sfx: model is required. The output is always mp3. Without durationMs the estimate bills the 22 s cap.
• sprite: source is a $ref or $file. birefnet removes the background on fal; none skips the call when the source is already transparent.

music and sfx have no default model. The runner hashes the input as written, so a default would hide a provider choice in the artifact key.

Models and prices

These are the bundled tables. priceOverrides changes a row or adds one, and a model with no price fails the estimate instead of counting as $0. app.fal.models(task) prints the same list from the running app, with each model's effective price.

Video

input.model is one of these aliases. Any other value fails the item before any upload.

Image refs are the references after the first frame. A ref with an audio/* MIME type is an audio ref, a video/* one is a video ref, every other ref is an image. Too many refs of one kind fail the item before any upload. minimax-h3-max-extend continues a clip: put the source clip in input.image.

Video prices are USD per second of output. The lookup is <alias>@<resolution>, then <alias>+audio when audio is on, then <alias>.

Cost is seconds × USD/s plus a reference surcharge on two models. minimax-h3-max-ref and minimax-h3-max-extend include 4096 reference tokens and bill 0.02 USD per 1000 above that (<alias>#refTokensIncluded, <alias>#refTokenUsdPer1k). minimax-h3-ref includes 5 images and bills 0.08 USD per extra one (minimax-h3-ref#refImagesIncluded, minimax-h3-ref#refImageUsd). Seedance 2.5 and 2.0 Mini have no bundled 1080p price: add seedance-2.5@1080p to priceOverrides to use it.

Image

Keys are image:<alias>@<resolution>, then image:<alias>. GPT Image rows are the high quality price. params.quality xhigh multiplies the row by 1.78, max by 4. Nano Banana 2.1 has no fal list price: it uses Pro's as an upper bound.

prompt-gen

model is any OpenRouter id, as long as it has a price. USD per million tokens.

Keys are llm:<id>#in and llm:<id>#out. Also priced, not listed: anthropic/claude-haiku-4.5 (1 / 5) and google/gemini-2.5-flash (0.3 / 2.5). The actual cost is fal's usage.cost when fal reports it, else the token counts at the table price.

Music, sfx and sprite

Keys are music:<alias>, sfx:<alias> and sprite:<alias>.

Config

pluginConfigs.fal. Flat keys, shallow merge.

API

Mounted at app.fal, reachable with ctx.require(falPlugin). No method makes a network call except upload.

FalTask is "video" | "image" | "prompt-gen" | "music" | "sfx" | "sprite". The price shape narrows on "inputPerM" in info.price.

import { app } from "./app";

for (const model of app.fal.models("video")) {
  if ("inputPerM" in model.price) continue;
  console.log(model.id, model.price.usd, "per", model.price.per);
}

console.log(app.fal.info().configured);

upload returns a URL fal can read. Use it to host a portrait before registering it with ark:

import { app } from "./app";

const image = { path: "faces/mira.png", mimeType: "image/png", hash: "a".repeat(64) };
const { url } = await app.fal.upload(image);
const record = await app.asset.register({ image, url }, { provider: "ark" });
console.log(record.assetId);

Errors

The classes are FalErrors.RetryableProviderError, FalErrors.TerminalProviderError and FalErrors.FlaggedProviderError. Messages start with [ai] and never contain the key or the prompt.

Events

Emits

None.

Listens to

None.

Depends on

• registry: the six register calls.

Related

• Video shots: keyframe, clip and score in one build file.
• video plugin: the request shape and the submit + poll contract.
• apimodels plugin: the same Seedance aliases, with real faces.
• ark plugin: Seedance straight from ByteDance, drafts and assets.