PHPackages marceloeatworld/falai-php - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. marceloeatworld/falai-php ActiveLibrary[API Development](/categories/api) marceloeatworld/falai-php ========================= Professional PHP client for the fal.ai serverless AI platform v2.0.0(1mo ago)105.5k↓11.1%4MITPHPPHP ^8.2 Since Nov 20Pushed 1mo ago2 watchersCompare [ Source](https://github.com/marceloeatworld/falai-php)[ Packagist](https://packagist.org/packages/marceloeatworld/falai-php)[ RSS](/packages/marceloeatworld-falai-php/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (3)Dependencies (5)Versions (5)Used By (0) fal.ai PHP Client ================= [](#falai-php-client) Professional PHP client for the [fal.ai](https://fal.ai) serverless AI platform, built on [Saloon v4](https://docs.saloon.dev). Requirements ------------ [](#requirements) - PHP 8.2+ Installation ------------ [](#installation) ``` composer require marceloeatworld/falai-php ``` Quick Start ----------- [](#quick-start) ``` use MarceloEatWorld\FalAI\FalAI; $fal = new FalAI('your-api-key'); // Synchronous execution $result = $fal->run('fal-ai/flux/schnell', [ 'prompt' => 'a sunset over mountains', 'image_size' => 'landscape_16_9', ]); $images = $result->json('images'); ``` Queue (Async Workflow) ---------------------- [](#queue-async-workflow) For long-running models, use the queue to submit jobs and retrieve results later. ``` // Submit a job $job = $fal->queue->submit('fal-ai/flux/schnell', [ 'prompt' => 'a sunset over mountains', ]); echo $job->requestId; // Check status $status = $fal->queue->status('fal-ai/flux/schnell', $job->requestId); echo $status->status->value; // IN_QUEUE, IN_PROGRESS, COMPLETED echo $status->queuePosition; // position in queue (if queued) // Get result when completed $result = $fal->queue->result('fal-ai/flux/schnell', $job->requestId); $images = $result->json('images'); // Cancel a job $fal->queue->cancel('fal-ai/flux/schnell', $job->requestId); ``` Subscribe (Submit + Auto-Poll) ------------------------------ [](#subscribe-submit--auto-poll) Submit a job and automatically poll until it completes. ``` use MarceloEatWorld\FalAI\Data\QueueStatus; $result = $fal->queue->subscribe('fal-ai/flux/schnell', [ 'prompt' => 'a sunset over mountains', ], pollInterval: 500, timeout: 300, requestTimeout: 120, onStatus: function (QueueStatus $status) { echo "Status: {$status->status->value}\n"; foreach ($status->logs as $log) { echo " {$log['message']}\n"; } }); $images = $result->json('images'); ``` Webhooks -------- [](#webhooks) Receive results via webhook instead of polling. ``` $job = $fal->queue->submit('fal-ai/flux/schnell', [ 'prompt' => 'a sunset over mountains', ], webhook: 'https://your.app/webhook'); ``` File Upload ----------- [](#file-upload) Upload local files to fal.ai storage for use with image-to-image models. ``` $url = $fal->storage->upload('/path/to/image.png', 'image/png'); $result = $fal->run('fal-ai/imageutils/rembg', [ 'image_url' => $url, ]); ``` Queue Options ------------- [](#queue-options) Fine-tune queue behavior with named parameters. ``` use MarceloEatWorld\FalAI\Enums\Priority; $job = $fal->queue->submit('fal-ai/flux/schnell', [ 'prompt' => 'test', ], webhook: 'https://your.app/webhook', timeout: 300, priority: Priority::Normal, runnerHint: 'session-abc', noRetry: true, ); ``` Custom Base URLs ---------------- [](#custom-base-urls) Override default endpoints if needed. ``` $fal = new FalAI( apiKey: 'your-api-key', queueBaseUrl: 'https://queue.fal.run', syncBaseUrl: 'https://fal.run', storageBaseUrl: 'https://rest.alpha.fal.ai', ); ``` Laravel Integration ------------------- [](#laravel-integration) Add to `config/services.php`: ``` 'falai' => [ 'api_key' => env('FAL_KEY'), ], ``` Register in a service provider: ``` $this->app->singleton(\MarceloEatWorld\FalAI\FalAI::class, function () { return new \MarceloEatWorld\FalAI\FalAI(config('services.falai.api_key')); }); ``` Use via injection: ``` use MarceloEatWorld\FalAI\FalAI; public function generate(FalAI $fal) { $result = $fal->queue->subscribe('fal-ai/flux/schnell', [ 'prompt' => 'A mountain landscape', ]); return $result->json('images'); } ``` Error Handling -------------- [](#error-handling) The client throws Saloon exceptions on HTTP errors (4xx/5xx). Queue subscribe also throws on job failures and timeouts. ``` use Saloon\Exceptions\Request\RequestException; try { $result = $fal->run('fal-ai/flux/schnell', ['prompt' => 'test']); } catch (RequestException $e) { echo $e->getResponse()->status(); echo $e->getResponse()->body(); } try { $result = $fal->queue->subscribe('fal-ai/flux/schnell', ['prompt' => 'test']); } catch (\RuntimeException $e) { echo $e->getMessage(); // timeout or job failure } ``` Architecture ------------ [](#architecture) ``` src/ FalAI.php # Entry point Auth/FalKeyAuthenticator.php # Authorization: Key {token} Connectors/ FalConnector.php # Abstract base (auth, headers, timeouts) QueueConnector.php # queue.fal.run SyncConnector.php # fal.run StorageConnector.php # rest.alpha.fal.ai Resources/ QueueResource.php # submit, status, result, cancel, subscribe StorageResource.php # upload Requests/ Queue/SubmitRequest.php Queue/StatusRequest.php Queue/ResultRequest.php Queue/CancelRequest.php Sync/RunRequest.php Storage/InitiateUploadRequest.php Data/ QueuedJob.php # Submit response DTO QueueStatus.php # Status check DTO Enums/ Status.php # InQueue, InProgress, Completed Priority.php # Normal, Low ``` License ------- [](#license) MIT Credits ------- [](#credits) - Built with [Saloon v4](https://github.com/saloonphp/saloon) - [fal.ai API Documentation](https://docs.fal.ai) ### Health Score 50 — FairBetter than 95% of packages Maintenance91 Actively maintained with recent releases Popularity31 Limited adoption so far Community12 Small or concentrated contributor base Maturity54 Maturing project, gaining track record Bus Factor1 Top contributor holds 50% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~247 days Total 3 Last Release 43d ago Major Versions v1.1.0 → v2.0.02026-03-29 PHP version history (2 changes)v1.0.0PHP ^8.1.0 v2.0.0PHP ^8.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/b50b46eb9dc22e81943c192896b4c697c18a2d30bc914948c46a3106637a59f9?d=identicon)[marceloeatworld](/maintainers/marceloeatworld) --- Top Contributors [![Bloafer](https://avatars.githubusercontent.com/u/317470?v=4)](https://github.com/Bloafer "Bloafer (4 commits)")[![marceloeatworld](https://avatars.githubusercontent.com/u/20625497?v=4)](https://github.com/marceloeatworld "marceloeatworld (4 commits)") --- Tags aiapi-clientfal-aifluximage-generationlaravelmachine-learningphpsaloonsdkserverlessstable-diffusionphpaisaloonserverlessfalfal-aiimage-generation ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/marceloeatworld-falai-php/health.svg) ``` [![Health](https://phpackages.com/badges/marceloeatworld-falai-php/health.svg)](https://phpackages.com/packages/marceloeatworld-falai-php) ``` ### Alternatives [sandorian/moneybird-api-php Moneybird API client for PHP 127.3k](/packages/sandorian-moneybird-api-php) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)