README

A lightweight PHP client for FAL.AI built with Saloon v3. Create AI-powered content with ease.

Features

• 🎨 Support for all FAL AI models (Recraft, Flux Pro, etc.)
• 🔄 Full queue system with status tracking
• 📡 Webhook support
• 🛠️ ComfyUI & Workflows support
• ⚡ Simple, intuitive API

Installation

composer require marceloeatworld/falai-php

Quick Start

use MarceloEatWorld\FalAI\FalAI;

$falAI = new FalAI('your-api-key');

// Generate an image
$result = $falAI->generations()->create('fal-ai/recraft-v3', [
    'prompt' => 'A beautiful landscape',
    'negative_prompt' => 'low quality',
    'image_size' => 'square_hd'
    'seed' => '42'
]);

// Check generation status using requestId
$status = $falAI->generations()->checkStatus($result->requestId);

// Get final result when completed
$finalResult = $falAI->generations()->getResult($result->requestId);

Models & Workflows

// FAL AI Models
$result = $falAI->generations()->create('fal-ai/flux-pro/v1.1-ultra', [
    'prompt' => 'A futuristic city',
    'negative_prompt' => 'low quality',
    'image_size' => 'square_hd'
    'seed' => '42'
]);

// ComfyUI Workflows
$result = $falAI->generations()->create('comfy/youraccount/workflow', [
    'loadimage_1' => 'https://example.com/image.jpg',
    'prompt' => 'Make it anime style'
    'seed' => '42'
]);

// Track any generation with requestId
$status = $falAI->generations()->checkStatus($result->requestId);

Advanced Usage

// Use webhooks
$result = $falAI->generations()
    ->withWebhook('https://your-site.com/webhook')
    ->create('fal-ai/recraft-v3', [
        'prompt' => 'A serene lake'
        'seed' => '42'
    ]);

// Cancel a generation using requestId
$cancelled = $falAI->generations()->cancel($result->requestId);

Response Structure

The GenerationData object contains:

• requestId: Unique identifier for tracking the generation
• responseUrl: URL to fetch the result
• statusUrl: URL to check status
• cancelUrl: URL to cancel generation
• status: Current status (IN_QUEUE, IN_PROGRESS, COMPLETED, ERROR)
• payload: Generation result data when completed
• error: Error message if any

Tracking Generations

// Store the requestId after creation
$requestId = $result->requestId;

// Later, check status
$status = $falAI->generations()->checkStatus($requestId);

if ($status->status === 'COMPLETED') {
    // Get the final result
    $finalResult = $falAI->generations()->getResult($requestId);
    // Access the generated images
    $images = $finalResult->payload['images'] ?? [];
}

Laravel Integration

Add to config/services.php:

'falai' => [
    'api_key' => env('FAL_API_KEY'),
],

Register in a service provider:

public function register()
{
    $this->app->singleton(FalAI::class, function () {
        return new FalAI(config('services.falai.api_key'));
    });
}

Use in controllers:

use MarceloEatWorld\FalAI\FalAI;

public function generate(FalAI $falAI)
{
    $result = $falAI->generations()->create('fal-ai/recraft-v3', [
        'prompt' => 'A mountain landscape'
        'seed' => '42'
    ]);
    
    // Store requestId for later use
    $requestId = $result->requestId;
}

public function checkStatus(FalAI $falAI, string $requestId)
{
    return $falAI->generations()->checkStatus($requestId);
}

Support & Security

For security issues, please email diagngo@gmail.com.

License

MIT License - see LICENSE.

Credits

• Built with Saloon v3
• Inspired by replicate-php