Skip to content
Nappai Documentation

Fal.ai Image Generator

Fal.ai Image Generator is a tool in Nappai that lets you create images from text or from existing images using the powerful Fal.ai AI models. You can choose the style, size, and number of images, and even add a “negative prompt” to tell the model what you don’t want in the picture.

How it Works

When you run the component, Nappai sends your settings and any image files you provide to the Fal.ai API. Fal.ai processes the request and returns one or more image files. The component then makes those images available to the rest of your workflow as a binary file (the Image output) or as a tool that an AI agent can call (the Tool output).

Inputs

Mapping Mode

This component has a special mode called “Mapping Mode”. When you enable this mode using the toggle switch, an additional input called “Mapping Data” is activated, and each input field offers you three different ways to provide data:

  • Fixed: You type the value directly into the field.
  • Mapped: You connect the output of another component to use its result as the value.
  • Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

  • Image Files: The list of image files (URL or File Id) to use for image generation.
  • Generation Mode: Mode of Image generation. (text_to_image or image_to_image)
  • Height: Height of the generated image in pixels (for custom size).
  • Image to Image mode: Mode of video generation.
  • Image size / Aspect Ratio: The size/aspect ratio of the generated image.
  • Mapping Mode: Enable mapping mode to process multiple data records in batch.
  • Image Model: The Fal.ai model to use for image generation.
  • Negative Prompt: What you don’t want in the image (supported by most models).
  • Number of Images: The number of images to generate (1‑4).
  • Prompt: A text description of the desired image(s). Maximum length varies by model.
  • Model Specific Parameters: Parameters specific to each model. See model documentation for details. https://fal.ai/models
  • Width: Width of the generated image in pixels (for custom size).
  • Tool Name: The name of the tool that will be used when this component is connected as a tool. This name will be displayed to the agent when it selects tools to use.
  • Tool Description: A detailed description of what this tool does. This description will help the agent understand when and how to use this tool effectively.
  • Tools arguments metadata: Defines the arguments metadata for the tools.

Credential
This component requires a Fal.ai API credential.

  1. First, add a new credential in the Nappai “Credentials” section and choose Fal.ai API.
  2. Enter your Fal.ai API Key (you can get it from fal.ai).
  3. In the component, select this credential from the Credential dropdown.

Note: The credential fields (API Key, etc.) are not shown in the Input Fields list.

Outputs

  • Image – Binary file(s) generated by Fal.ai (method: generate_image_file).
  • Tool – A tool object that can be used by an AI agent (method: to_toolkit).

Usage Example

  1. Set up the credential – Add a Fal.ai API credential and select it in the component.
  2. Configure the prompt – In the Prompt field, type “A futuristic city skyline at sunset.”
  3. Choose the model – Pick “fal-ai-image-gen” from the Image Model dropdown.
  4. Set image size – Leave Height and Width empty to use the model’s default size, or set them to 512 × 512 for a custom size.
  5. Number of images – Set Number of Images to 2 to get two variations.
  6. Run the component – The Image output will contain two image files that you can feed into a gallery component or send to a user.
  7. Optional – Mapping Mode – If you have a list of prompts in a previous component, enable Mapping Mode and map the Prompt field to that list. The component will generate an image for each prompt automatically.
  • Fal.ai Text Generator – Generates text using Fal.ai models.
  • Fal.ai Video Generator – Creates short videos from prompts or images.

Tips and Best Practices

  • Keep the Prompt concise; very long prompts may be truncated by the model.
  • Use Negative Prompt to exclude unwanted elements (e.g., “no text, no watermark”).
  • If you need a specific aspect ratio, choose it from Image size / Aspect Ratio instead of setting custom width/height.
  • For batch processing, enable Mapping Mode and feed a list of prompts or image URLs.
  • Store the generated images in a dedicated folder or database for easy retrieval later.

Security Considerations

  • Treat your Fal.ai API Key like a password. Do not share it publicly or commit it to version control.
  • Use Nappai’s credential management to keep the key encrypted and limit access to only the components that need it.
  • If you share a workflow that includes this component, make sure the recipient also has a valid Fal.ai API credential.