FAL Video Generation

This guide covers video generation using the FAL provider in the Go-AI SDK.

Overview

FAL provides high-quality video generation models through their API, including:

• Text-to-video generation
• Image-to-video animation
• Various quality and speed tiers (pro, standard, turbo)

Setup

import (
    "github.com/digitallysavvy/go-ai/pkg/providers/fal"
)

cfg := fal.Config{
    APIKey: os.Getenv("FAL_API_KEY"),
}

prov := fal.New(cfg)
model, err := prov.VideoModel("fal-ai/kling-video/v2.5-turbo/pro/image-to-video")

Image-to-Video

Using URL

result, err := model.DoGenerate(ctx, &provider.VideoModelV3CallOptions{
    Prompt:      "The cat slowly turns its head and blinks",
    AspectRatio: "16:9",
    Image: &provider.VideoModelV3File{
        Type: "url",
        URL:  "https://example.com/cat.jpg",
    },
})

Using Local File

// Read image file
imageData, err := os.ReadFile("cat.png")
if err != nil {
    log.Fatal(err)
}

result, err := model.DoGenerate(ctx, &provider.VideoModelV3CallOptions{
    Prompt:      "The cat slowly turns its head and blinks",
    AspectRatio: "16:9",
    Image: &provider.VideoModelV3File{
        Type:      "file",
        Data:      imageData,
        MediaType: "image/png", // Required for file uploads
    },
})

Supported Image Formats

For file-based uploads, FAL supports:

• JPEG (image/jpeg)
• PNG (image/png)
• WebP (image/webp)
• GIF (image/gif)

Implementation Details

When using file uploads:

• Image data is converted to a base64-encoded data URI
• Format: data:<mime-type>;base64,<base64-data>
• No separate upload step required
• Data is sent directly in the API request body

Parameters

Parameter	Type	Description
Prompt	string	Text description of desired video animation
AspectRatio	string	Video aspect ratio (e.g., "16:9", "9:16", "1:1")
Resolution	string	Video resolution (e.g., "1920x1080", "1280x720")
Duration	*float64	Video duration in seconds
FPS	*int	Frames per second (24, 30, 60)
Seed	*int	Seed for reproducible generation
Image	*VideoModelV3File	Input image (URL or file data)

Example

See complete example: examples/providers/fal/image-to-video-file.go

Memory Considerations

• Large images (>10MB) are loaded into memory and base64 encoded
• Base64 encoding increases size by ~33%
• This is acceptable for typical image sizes but should be considered for very large images

Best Practices

1. File Size: Keep images under 10MB for optimal performance
2. Format: Use JPEG or PNG for best compatibility
3. MIME Type: Always provide correct MediaType for file uploads
4. Error Handling: Handle encoding failures gracefully

Troubleshooting

"Invalid image data" error

• Verify the image file is not corrupted
• Check that the file size is reasonable (<10MB)
• Ensure the MIME type matches the actual file format

Request timeout

• Reduce image file size
• Try a different model tier (turbo vs pro)
• Increase timeout in provider options