Fal.ai is an optional image/video provider. It uses the official @fal-ai/client
on the server and the existing media import and generation-job paths. Enabling
Fal does not replace native OpenAI, Gemini, Seedance, Kling, or other providers.
- Start OpenChatCut using its normal development command (Node 24).
- Open Settings → AI Generation → Image → Fal.ai and save your API key.
Alternatively put
FAL_KEY=your-keyin the Git-ignored.env.local. - Select Fal.ai in the capability's default-provider dropdown, then select an image model. Repeat under Video → Fal.ai for a video model.
The same key serves both capabilities. Model defaults are non-secret
FAL_IMAGE_MODEL and FAL_VIDEO_MODEL; provider defaults use the existing
PREFERRED_IMAGE_VENDOR=fal and PREFERRED_VIDEO_VENDOR=fal settings. A blank
model choice asks for a selection; it does not silently choose Seedance.
An explicit model request in chat overrides the saved default.
Never use VITE_FAL_KEY or place the key in client code. The browser receives
only key-configuration status and non-secret model preferences. Fal generation
is billed to your Fal account, independently of the conversational assistant.
The catalog in shared/fal-models.ts is the source of truth
for settings, assistant model choices, limits, and allowed endpoint paths.
Each entry links to its official schema. Only listed modes and common inputs
are supported; this is not arbitrary access to every endpoint in Fal's catalog.
The assistant uses submit_image or submit_video with model: "fal" and a
falModel catalog ID. Omitting the ID uses a saved model choice; if neither is
present, the request fails locally before upload or generation. Unsupported
options and model-specific limits are validated before submission.
Project reference files upload from the server to Fal storage. No R2 account is needed. The local upload ceiling is 30 MB per image, 50 MB per video, and 15 MB per audio file; individual models can impose additional limits. Generated media uses OpenChatCut's existing URL validation, size/MIME checks, and media library.
Video jobs save the concrete model selection, endpoint, and Fal request ID. Polling or recovering a recorded job never submits a replacement generation. Image generation retains the existing synchronous request flow: after a process interruption or failed download, check Fal request history before generating again. Automatic durable image recovery is not implemented.
npm run verify:fal runs catalog validation, mocked queue recovery, official SDK
transport with mocked network, and provider-routing regression checks. It does
not require a real key and makes no paid generation calls. It also runs in the
normal npm test suite.
For an optional paid acceptance check, select Nano Banana 2 and request exactly one 1K square image. Verify it appears in the media library and in your Fal request history. Then select a video model and request one clip at its displayed minimum supported duration. Confirm the clip imports and plays in the timeline. Do not retry a stalled request until its status is known.
- Verify the official Fal input/output schemas, including the edit/frame modes.
- Add a catalog entry with a stable ID, official endpoint paths, documentation link, supported limits, and conservative defaults.
- Reuse a payload adapter only when the request fields really match. Otherwise
add a focused mapping in
server/plugins/fal-catalog-input.ts. - Add valid-mode fixtures and invalid-input checks to the catalog verification file. Test that unsupported controls fail before network activity.
- Run
npm run verify:fal,npm test,npm run lint, andnpm run build.
No dynamic endpoint URL, generic JSON escape hatch, or automatic catalog download is used. New models can be added without redesigning the editor or duplicating its generation workflow. Training, speech, 3D, video editing/extension, masks, and provider-specific advanced controls are outside this initial integration unless explicitly listed for a catalog entry.