Skip to content
LOPS Docs

Fal.ai Operator

v1.3.3Updated

The fal.ai operator provides a direct interface to fal.ai’s image and video generation models. When you select an Endpoint ID, the operator fetches the API schema and dynamically creates input parameters on the API Parameters page, so the interface always matches the selected model’s requirements.

Agent Tool Integration

Section titled “Agent Tool Integration”
🔧 GetTool Enabled 1 tool

This operator exposes 1 tool that allow Agent and Gemini Live LOPs to generate images, videos, or other media using the configured fal.ai endpoint with dynamically filtered parameters.

Use the Tool Debugger operator to inspect exact tool definitions, schemas, and parameters.

The operator exposes a create_media tool. Which parameters the agent can control is determined by the GetTool Par Filter setting on the API Parameters page — use wildcard patterns like * (all), prompt (exact match), or * ^seed (all except seed).

Requirements

Section titled “Requirements”
  • fal.ai API Key — enter on the API page or store in ChatTD’s KeyManager
  • fal-client package — pulse Install Dependencies on the API page if not already installed

Input/Output

Section titled “Input/Output”

Inputs

Section titled “Inputs”

No wire inputs. For image-based models (image-to-image, inpainting), the operator dynamically creates TOP parameters on the API Parameters page — connect any TOP to these.

Outputs

Section titled “Outputs”
  • out1 (TOP): Generated image or video as a texture
  • out2 (Text DAT): Full JSON response from the API call
  • out3 (Table DAT): Execution log with timestamps, status, duration, and results

Usage Examples

Section titled “Usage Examples”

Text-to-Image Generation

Section titled “Text-to-Image Generation”
  1. On the API page, select an Endpoint ID such as fal-ai/flux/dev
  2. Wait for the API Parameters page to populate with dynamic parameters
  3. Enter a prompt in the generated prompt field
  4. Pulse Execute / Call on the API Parameters page
  5. The generated image appears in the out1 TOP output

Image-to-Image

Section titled “Image-to-Image”
  1. Select an endpoint that supports image inputs, such as fal-ai/flux/dev/image-to-image
  2. On the API Parameters page, connect a TOP to the dynamically created image parameter
  3. Enter a prompt to guide the transformation
  4. Pulse Execute / Call — the result appears in out1

Saving Output to Disk

Section titled “Saving Output to Disk”
  1. On the History page, enable Auto Save Images
  2. Set a Save Path and optionally configure the Naming Pattern (supports {timestamp}, {endpoint}, {counter})
  3. Choose a Save Format or leave as “Auto (Detect)”
  4. Generated images are automatically saved after each execution

Endpoint Discovery

Section titled “Endpoint Discovery”

The Endpoint ID dropdown includes a curated list of popular models. You can also type any valid fal.ai endpoint ID directly (format: fal-ai/model-name). Pulse Discover Endpoints on the API page to fetch additional available endpoints. Visit fal.ai/models to browse the full model gallery.

Parameters

Section titled “Parameters”

API Parameters

Section titled “API Parameters”
Status (Status) op('fal_ai').par.Status Str

Current operation status

Default:
"" (Empty String)
Active (Active) op('fal_ai').par.Active Toggle
Default:
False
Execute / Call (Execute) op('fal_ai').par.Execute Pulse

Execute the API call with current parameters

Default:
False
GetTool Par Filter (Apiparfilter) op('fal_ai').par.Apiparfilter Str

Pattern to match which parameters agents can control (* for all, prompt for just prompt, etc.)

Default:
"" (Empty String)
Allow Tool Parameter Updates (Allowtoolparamupdates) op('fal_ai').par.Allowtoolparamupdates Toggle

If enabled, allows AI agent tool calls to update the operator parameters.

Default:
False
API Parameters Header

API

Section titled “API”
API Key (Apikey) op('fal_ai').par.Apikey Str

fal.ai API key for authentication

Default:
"" (Empty String)
Refresh Endpoint (Refreshendpoint) op('fal_ai').par.Refreshendpoint Pulse

Refresh endpoint schema and rebuild parameters

Default:
False
Discover Endpoints (Discoverendpoints) op('fal_ai').par.Discoverendpoints Pulse

Discover available fal.ai endpoints

Default:
False
Install Dependencies (Installdependencies) op('fal_ai').par.Installdependencies Pulse

Install required fal-client package

Default:
False
Enable Logging (Enablelogging) op('fal_ai').par.Enablelogging Toggle

Log operations to console and tables

Default:
False
Enable Execution (Enableexecution) op('fal_ai').par.Enableexecution Toggle

Enable API execution

Default:
False
Execution Mode (Executionmode) op('fal_ai').par.Executionmode Menu

How to execute the API call

Default:
sync
Options:
sync, async, queue
Endpoint ID (Endpoint) op('fal_ai').par.Endpoint StrMenu

fal.ai endpoint ID (e.g., fal-ai/flux/dev)

Default:
"" (Empty String)
Menu Options:
  • fal-ai/flux/dev (fal-ai/flux/dev)
  • fal-ai/flux-pro/kontext (fal-ai/flux-pro/kontext)
  • fal-ai/imagen4/preview (fal-ai/imagen4/preview)
  • fal-ai/flux-pro/v1.1-ultra (fal-ai/flux-pro/v1.1-ultra)
  • fal-ai/recraft/v3 (fal-ai/recraft/v3)
  • fal-ai/hidream-i1-full (fal-ai/hidream-i1-full)
  • fal-ai/hidream-i1-dev (fal-ai/hidream-i1-dev)
  • fal-ai/hidream-i1-fast (fal-ai/hidream-i1-fast)
  • fal-ai/ideogram/v2 (fal-ai/ideogram/v2)
  • fal-ai/stable-diffusion-v35-large (fal-ai/stable-diffusion-v35-large)
  • fal-ai/flux-lora/inpainting (fal-ai/flux-lora/inpainting)
  • fal-ai/flux-general (fal-ai/flux-general)
  • fal-ai/flux-lora (fal-ai/flux-lora)
  • fal-ai/flux/dev/image-to-image (fal-ai/flux/dev/image-to-image)
  • fal-ai/aura-sr (fal-ai/aura-sr)
  • fal-ai/clarity-upscaler (fal-ai/clarity-upscaler)
  • fal-ai/calligrapher (fal-ai/calligrapher)

History

Section titled “History”
Select Image (Selectimage) op('fal_ai').par.Selectimage Int
Default:
1
Range:
0 to 1
Slider Range:
1 to 12
Auto Save Images (Autosave) op('fal_ai').par.Autosave Toggle

Automatically save generated images to disk

Default:
False
Save Path (Savepath) op('fal_ai').par.Savepath Str

Path where images will be saved (supports expressions)

Default:
"" (Empty String)
Save Format (Saveformat) op('fal_ai').par.Saveformat Menu

Image format for saved files. Auto detects from response.

Default:
auto
Options:
auto, png, jpg, tiff, exr
Save Quality (Savequality) op('fal_ai').par.Savequality Float

Compression quality (0.0-1.0)

Default:
0.0
Range:
0 to 1
Slider Range:
0 to 1
Naming Pattern (Savenamingpattern) op('fal_ai').par.Savenamingpattern Str

File naming pattern. Available variables: {timestamp}, {endpoint}, {counter}

Default:
"" (Empty String)
Save Base64 in JSON (Savebase64injson) op('fal_ai').par.Savebase64injson Toggle

If enabled, saves base64 image data in the settings JSON. If disabled, saves the TOP path.

Default:
False
History Table (Historytable) op('fal_ai').par.Historytable DAT

Reference to full history table (one row per output file)

Default:
"" (Empty String)
Last Results Local (Resultslocal) op('fal_ai').par.Resultslocal DAT

Reference to local file results (filtered from results table)

Default:
"" (Empty String)
Last Results URL (Resultsurl) op('fal_ai').par.Resultsurl DAT

Reference to URL results (filtered from results table)

Default:
"" (Empty String)

Agent

Section titled “Agent”
Agent Execution Mode (Agentexecutionmode) op('fal_ai').par.Agentexecutionmode Menu

Controls how agent tool calls execute. "Wait" blocks until generation completes and returns the file path. "Background" starts generation and returns immediately.

Default:
wait
Options:
wait, background
Agent Result Content (Agentresultcontent) op('fal_ai').par.Agentresultcontent Menu

Controls what is returned to the agent. "Path" returns the local file path for display/further processing.

Default:
status_only
Options:
status_only, path_only, path_with_metadata

Changelog

Section titled “Changelog”
v1.3.32026-03-01
  • Fix fal_ai operator image handling and tool calls
v1.3.22025-12-21
  • Add History page and convert the Auto Save page previously to History page fully. there is also now Selectimage parameter that selects from the main history table that shows all outputs in a table. also the History page paramter has 3 parameters that show tha ttables for the history table and also 2 talbes for the recent result, one that is local and one that is url based.
  • Update README to accurately reflect current file type support (images and video only) - Add devlog/todo/3d-audio-support.md planning document for future file type expansion - Document planned 3D and audio format handling for Meshy, SAM, and audio generation endpoints
  • Update README to reflect 600+ model access and dynamic endpoint support
  • Add professional README with operator description and changelog links
v1.3.12025-12-20
  • Add auto-detection for image format (detects PNG/JPG from response headers, URL, or PIL format) - Change default save format from jpg to auto - Add full history table tracking all output files (one row per file) - Add history table columns: output_file, job_id, timestamp, endpoint, status, prompt, duration_sec - Add read-only DAT parameters for history browsing: Historytable, Resultslocal, Resultsurl - Add Selectimage parameter auto-sync with history table size - Add video output tracking to history table - Add qwen-image-layered endpoint to endpoint list
  • Initial commit
v1.3.02025-07-22
  • Feature: Added Allow Tool Parameter Updates toggle to the API Parameters page. This allows users to prevent AI agent tool calls from modifying the operator's UI parameters.
  • Refactor: The core execution logic (execute_async) now accepts optional arguments. This allows tool calls to provide parameters for a run without changing the values in the UI, ensuring consistent behavior when the new toggle is disabled.
  • Fix: Corrected tool call behavior so that it always uses the parameters sent by the agent for the API call, while the new toggle only controls whether the UI is updated with those parameters.
v1.2.02025-07-20
  • FEAT: Added a toggle (Save Base64 in JSON) to control how image parameters are saved in the companion _settings.json file. When enabled, it saves the full base64 data URI; when disabled, it saves the local TouchDesigner TOP path for better readability and smaller file size.
  • FEAT: Added auto-saving of generation parameters to a companion _settings.json file for both images and videos. This ensures full reproducibility of results.
  • FEAT: Added full integration with the AI Agent framework.
    • Implemented GetTool() to dynamically generate a tool definition based on the selected endpoint's schema and the Agent Parameter Filter.
    • Implemented HandleToolCall() to allow AI agents to execute the operator by setting parameters and triggering the API call.
    • This allows the fal_ai operator to be used as a function-callable tool within an agentic workflow.
  • FIX: Corrected an issue where parameters with "input image" in their description (e.g., aspect_ratio) were incorrectly created as image (TOP) inputs instead of their proper type (e.g., Menu). The parameter creation heuristic is now more specific.
  • FIX: Resolved an error where API calls would fail if a JSON array parameter (like loras) was empty. The operator now omits these parameters from the request payload if they are empty, accommodating APIs that do not accept empty lists.
v1.1.02025-07-20

🎬 NEW: Video Generation Support

  • Video Result Processing: Added support for video generation results in the results table
    • Video URLs are now properly detected and stored as video_url entries
    • Maintains consistent format with existing image URL handling
  • Video Auto-save: Extended auto-save functionality to handle video files
    • Automatic video downloads when auto-save is enabled
    • Smart file extension detection from content-type (mp4, webm, mov) or original filename
    • Reuses existing path/filename generation logic with video-specific extensions
  • Local File Tracking: Added local_file entries to results table
    • Shows local file paths for both images and videos when auto-saved
    • Provides complete tracking from URL to local storage location
  • File Parameter Integration: Auto-saved files now update the local_result operator's file parameter
    • Enables immediate viewing/processing of generated content
    • Works for both images and videos

    🔧 Enhanced Auto-save System

    • Unified File Handling: Streamlined file saving logic to handle both images and videos
    • Smart Extension Detection: Automatic file extension selection based on content metadata
    • Improved Results Table: Clear separation between original URLs and local file paths

    ⚙️ Configuration Updates

    • Auto-save Default: Changed default auto-save setting to enabled for better user experience
    • Consistent Interface: Video handling follows same patterns as existing image functionality

    This update extends the operator's capabilities to handle video generation endpoints while maintaining backward compatibility and consistent user experience.

v1.0.02025-07-14

🎉 NEW OPERATOR: fal_ai - Dynamic AI Image Generation

This is a brand new operator that provides a comprehensive interface to fal.ai's image generation APIs with advanced dynamic parameter discovery and tool integration.

🔧 Core Features

  • Dynamic Parameter Discovery: Automatically fetches OpenAPI schemas from fal.ai endpoints and creates TouchDesigner parameters on-the-fly
  • Multiple Execution Modes: Synchronous, asynchronous, and queue-based API execution
  • Smart Image Handling: Automatic TOP-to-base64 conversion for image input parameters
  • Auto-save System: Configurable automatic saving of generated images with custom naming patterns
  • Tool Integration: Full GetTool support for AI agent control with parameter filtering
  • Comprehensive Logging: Detailed execution tracking and error handling

📊 Dynamic Parameter System

  • Schema-based Generation: Reads OpenAPI schemas and creates appropriate TD parameter types (int, float, string, menu, TOP)
  • Smart Parameter Detection: Automatically identifies image URL parameters and converts them to TOP parameters
  • Parameter Tracking: Internal table system tracks all dynamic parameters and their API mappings
  • Intelligent Cleanup: Smart parameter management that only recreates parameters when definitions change

🖼️ Image Generation Endpoints

Pre-configured support for popular fal.ai image generation models:

  • FLUX.1 [dev] and [schnell]
  • FLUX Pro variants (v1.1-ultra, kontext)
  • Imagen4 Preview
  • Recraft V3
  • HiDream variants (i1-full, i1-dev, i1-fast)
  • Ideogram V2
  • Stable Diffusion V3.5 Large
  • Aura SR (Super Resolution)
  • Clarity Upscaler
  • And more...

🔑 API Key Management

  • Multiple Storage Options: Supports both local config files and ChatTD KeyManager integration
  • Secure Handling: API keys are never displayed in plain text in parameters
  • Auto-detection: Automatically loads keys from available sources
  • Easy Setup: Simple key entry and storage workflow

⚙️ Execution Features

  • Three Execution Modes:
    • Sync: Immediate execution with blocking
    • Async: Non-blocking execution with progress tracking
    • Queue: Queue-based execution for batch processing
  • Progress Tracking: Real-time execution status and timing
  • Error Handling: Comprehensive error reporting and recovery
  • Result Processing: Intelligent parsing of API responses into actionable data

🎯 AI Agent Integration

  • GetTool Support: Exposes filtered parameters as tool definitions for AI agents
  • Parameter Filtering: Configurable pattern matching for which parameters agents can control
  • Tool Execution: HandleToolCall method for seamless agent integration
  • Response Formatting: Structured tool responses for reliable agent interaction

💾 Auto-save System

  • Flexible Patterns: Configurable file naming with timestamp, endpoint, and counter variables
  • Multiple Formats: Support for PNG, JPEG, TIFF, and EXR formats
  • Quality Control: Adjustable compression settings
  • Path Expressions: Support for TouchDesigner expressions in save paths
  • Async Downloads: Non-blocking image downloads and saving

📈 Data Management

  • Execution History: Complete log of all API calls with timing and status
  • Parameter Debugging: Table showing all discovered parameters and their properties
  • Dynamic Tracking: Real-time tracking of parameter mappings and states
  • Results Parsing: Structured output tables for easy data access
  • JSON Response Storage: Full API responses stored in text DATs

🔄 State Management

  • Endpoint Caching: Intelligent caching of OpenAPI schemas to reduce API calls
  • Session Tracking: Maintains state across parameter changes and endpoint switches
  • Auto-refresh: Automatic schema refresh when endpoints change
  • Dependency Checking: Built-in dependency management with installation prompts

🛠️ Developer Features

  • Comprehensive Reset: ResetOp function clears all data, parameters, and logs
  • Debug Logging: Detailed logging with multiple severity levels
  • Error Recovery: Graceful handling of network errors and API failures
  • Extension Architecture: Built on DotLOPUtils for consistency with other LOP operators

🎨 Output Integration

  • Automatic Sizing: Updates get_output operator resolution based on generated image dimensions
  • Multiple Outputs: Supports both image URLs and direct image data
  • Format Detection: Intelligent parsing of different API response formats
  • Result Tables: Structured data output for downstream processing

⚡ Performance Optimizations

  • Smart Parameter Management: Only recreates parameters when necessary
  • Efficient Caching: Schema caching reduces redundant API calls
  • Async Operations: Non-blocking execution prevents UI freezing
  • Memory Management: Proper cleanup of dynamic parameters and data structures

This operator represents a new paradigm for AI service integration in TouchDesigner, providing both powerful automation capabilities and fine-grained manual control.

Section titled “Related Operators”