Fal AI Model Search & Integration

Guide for searching and integrating Fal AI models from fal.ai platform.

Workflow

1. Search Models

When user wants to find a model, use WebFetch to search:

https://fal.ai/explore/search?q=<search-query>

Process:

• Parse search results - look for model IDs in format <namespace>/<model-name> (e.g., fal-ai/flux-schnell , xai/grok-imagine-image )

• Extract: model ID, category (text-to-image, image-to-image, etc.), description

• Present the found models to the user with:

• Model name and category

• Description

• Playground link: https://fal.ai/models/&#x3C;full-model-id> (for xai: https://fal.ai/models/xai/&#x3C;model> ; others: https://fal.ai/models/fal-ai/&#x3C;model> )

• Wait for user confirmation on which model to use

Important: The full Model ID format depends on the model namespace:

Search Result Full Model ID API Endpoint

xai/grok-imagine-image

xai/grok-imagine-image

https://fal.run/xai/grok-imagine-image

bytedance/seedream/v4.5/...

fal-ai/bytedance/seedream/v4.5/...

https://fal.run/fal-ai/bytedance/seedream/v4.5/...

flux-1/schnell

fal-ai/flux-1/schnell

https://fal.run/fal-ai/flux-1/schnell

Rule: xai/ models use their ID directly; all others need fal-ai/ prefix.

2. Get Model Details

Once user confirms a model, fetch its detailed information:

URL Pattern Rules:

Model Prefix llms.txt URL Playground URL Full Model ID

xai/

https://fal.ai/models/xai/&#x3C;name>/llms.txt

https://fal.ai/models/xai/&#x3C;name>

xai/<name>

Others https://fal.ai/models/fal-ai/&#x3C;id>/llms.txt

https://fal.ai/models/fal-ai/&#x3C;id>

fal-ai/<id>

Rule: If model ID starts with xai/ , do NOT prepend fal-ai/ . For all other models, prepend fal-ai/ .

Examples:

• xai/grok-imagine-image → llms.txt: .../models/xai/grok-imagine-image/llms.txt , Playground: .../models/xai/grok-imagine-image

• bytedance/seedream/v4.5/text-to-image → llms.txt: .../models/fal-ai/bytedance/seedream/v4.5/text-to-image/llms.txt , Playground: .../models/fal-ai/bytedance/seedream/v4.5/text-to-image

When presenting model details to user, always include:

• Model ID

• Playground link: For interactive testing

• API endpoint: https://fal.run/&#x3C;full-model-id>

• Documentation links: llms.txt, API docs (https://fal.ai/models/&#x3C;full-model-id>/api )

Process:

• Parse the llms.txt content for:

• Model capabilities and use cases

• API endpoint and parameters

• Code examples

• Pricing information

• Present the key details to the user

• Confirm integration approach with user

3. Integration Guidelines

When integrating a Fal AI model:

• Check existing Fal client setup in the project

• Use the model ID returned from search (format: fal-ai/<model-name> )

• Follow the API patterns shown in the llms.txt examples

• Add proper error handling for API calls

4. User Confirmation Points

Always confirm with user at these stages:

• After search results: "Found these models: [list with links]. Which one would you like to use?"

• After model details: "Here are the details for [model] ([playground link]). Shall I proceed with integration?"

• Before code changes: "I'll integrate [model] by [changes]. Does this look correct?"

Link format for presentation:

• Use markdown format: description

• Always include the model's playground link so users can test it interactively

Common Model Patterns

Model Type Example IDs Use Case

Text to Image fal-ai/flux-schnell , xai/grok-imagine-image

Generate images from text

Image to Image fal-ai/flux-lora , xai/grok-imagine-image/edit

Transform existing images

Video fal-ai/ltx-video , fal-ai/veo2

Generate video content

Audio fal-ai/playht , fal-ai/xtts

Text-to-speech, audio generation

Example Output Format

When presenting search results to the user, use this format:

Found 3 models matching "flux":

1. fal-ai/flux-schnell (Text to Image)

   • Fastest Flux model for high-quality image generation
   • Playground | API Docs

2. fal-ai/flux-pro/v1.1 (Text to Image)

   • Professional-grade image generation with superior quality
   • Playground | API Docs

Which model would you like to use?

Error Handling

Error Cause Solution

No search results Query too specific or no matching models Suggest broader search terms or alternative keywords

Model not found (404) Wrong URL pattern Check if model starts with xai/ → use /models/xai/... URL; otherwise use /models/fal-ai/...

llms.txt returns empty Model deprecated or unavailable Inform user the model may be deprecated; suggest alternatives

API key error (401) Missing or invalid FAL_KEY

Check environment variable or prompt user to set FAL_KEY

Rate limit (429) Too many requests Implement exponential backoff; suggest retry after delay

Timeout Model inference taking too long For async models, use fal.queue.submit pattern with polling

Notes

• The llms.txt endpoint returns machine-readable documentation optimized for LLMs

• Model IDs can have various prefixes: fal-ai/ , xai/ , etc. - always use the full ID from search results

• Always present options to the user before making integration decisions