plugin-fal-ai

Generate videos using fal.ai's MiniMax Hailuo-02 text-to-video model directly from your ElizaOS agents.

Features

• 🎬 Generate videos from text descriptions
• ⚡ High-quality 768p resolution videos
• ⏱️ 6-second video generation (10-second option available)
• 🤖 Natural language understanding ("create video:", "text to video:", "generate video:")
• 📹 Automatic video attachment in responses
• ⚙️ Full error handling and validation
• 🎯 Prompt optimization for better results

Installation

bun add @your-username/plugin-fal-ai 

Setup

1. Get a fal.ai API Key

1. Visit fal.ai
2. Sign up for a free account
3. Go to Dashboard → API Keys
4. Create a new API key
5. Copy the key (starts with fal_)

2. Configure Environment

Add your API key to your .env file:

FAL_KEY=fal_your_actual_key_here

3. Add Plugin to Your Agent

Update your agent's character file (src/character.ts):

export const character = {
  // ... your character config
  plugins: [
    '@elizaos/plugin-bootstrap',
    '@your-username/plugin-fal-ai'  // Add this line
  ]
};

Or for local development, update your project's index.ts:

import falaiPlugin from '../plugin-fal-ai/dist/index.js';

export const projectAgent: ProjectAgent = {
  character,
  init: async (runtime: IAgentRuntime) => await initCharacter({ runtime }),
  plugins: [starterPlugin, falaiPlugin], // Add falaiPlugin here
  tests: [ProjectStarterTestSuite],
};

Usage

Once configured, your agent can generate videos with natural language:

• "Create video: a galactic smuggler navigating through space"
• "Text to video: dolphins jumping in crystal clear ocean water"
• "Generate video: a futuristic city with flying cars"
• "Make video: a magical forest with glowing mushrooms"

The agent will respond with the generated video attached.

Example Conversation

User: Create video: a spaceship flying through an asteroid field
Assistant: I'll create a 6-second video of a spaceship flying through an asteroid field!
[Video attached: spaceship-asteroid-field.mp4]

Video Specifications

MiniMax Hailuo-02 Model

• Resolution: 768p (1360x768)
• Duration: 6 seconds (default) or 10 seconds
• Format: MP4
• Generation Time: ~30-60 seconds
• Prompt Optimization: Automatically enabled for better results

Development

Local Development

When developing locally, use file path linking:

# In your agent project
bun add file:../plugin-fal-ai

Building

bun install
bun run build

Testing

Test in your agent:

elizaos start

Then chat with your agent and try generating videos!

API Limits

• Free tier: Limited video generations
• Paid plans available for higher usage
• See fal.ai pricing

Advanced Features

Camera Movements (Coming Soon)

The MiniMax model supports camera movement instructions:

• Pan left/right
• Zoom in/out
• Tilt up/down
• Tracking shots
• And more!

Duration Options

You can modify the action to support 10-second videos by changing the duration parameter in the code.

Troubleshooting

"FAL_KEY not found"

• Make sure FAL_KEY is in your .env file
• Restart your agent after adding the key

"No video returned"

• Check your API key is valid
• Ensure you have credits remaining
• Video generation can take 30-60 seconds

Action not triggering

• Verify plugin is in your project's plugins array
• Try using exact phrases: "Create video:" or "Text to video:"
• Check that the action name doesn't conflict with other plugins

Contributing

Contributions welcome! Please submit PRs to add:

• Camera movement support
• Duration selection in prompts
• Image-to-video capabilities
• Multiple video models
• Batch generation

License

MIT