Download the PHP package ianrodrigues/laravel-fal-ai without Composer

On this page you can find all versions of the php package ianrodrigues/laravel-fal-ai. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of ianrodrigues/laravel-fal-ai

Informations about the package laravel-fal-ai

Laravel fal.ai

Introduction

laravel-fal-ai is a third-party fal.ai driver for the official Laravel AI SDK. It plugs a fal provider into the SDK's manager so you may generate content with fal models through the same fluent API you use for OpenAI, Gemini, and the other bundled providers.

The package ships image generation today with two built-in handlers:

Its architecture is capability-scoped, so support for audio, video, and transcription can be added under parallel namespaces as fal expands.

Installation

You may install the package via Composer:

The service provider is registered automatically through Laravel's package discovery. No manual registration is required.

Requirements

Configuration

Set your fal API key in your application's .env file. You may grab a key from the fal dashboard:

Next, register the driver in your config/ai.php providers array:

If you would like to customize the package's defaults — timeouts, polling cadence, model handler registration — you may publish the configuration file:

This will place a fal-ai.php file in your config directory. The available options are documented in the Configuration Reference section.

Image Generation

The driver supports two usage surfaces. The first matches the upstream Laravel AI builder and is recommended when the SDK's standard options are all you need. The second is a fluent builder that exposes fal-specific knobs the upstream SDK does not yet surface for image generation.

Standard Laravel AI Builder

The SDK's size and quality arguments are translated to fal's vocabulary:

SDK value fal field fal value
->square() / 1:1 aspect_ratio 1:1
->portrait() / 2:3 aspect_ratio 2:3
->landscape() / 3:2 aspect_ratio 3:2
quality('low') resolution 0.5K
quality('medium') resolution 1K
quality('high') resolution 2K

Fluent fal Builder

When you need a fal-specific option (seed, num_images, safety_tolerance, and so on), use the Fal facade. It wraps the standard Image::of(...) builder and accepts every method the SDK exposes, plus methods for each fal parameter:

The following fal-only methods are available:

Method fal parameter
numImages(int) num_images
seed(int) seed
aspectRatio(string) aspect_ratio
resolution(string) resolution
safetyTolerance(int) safety_tolerance
outputFormat(string) output_format
systemPrompt(string) system_prompt
thinkingLevel(string) thinking_level
enableWebSearch(bool) enable_web_search
limitGenerations(int) limit_generations

For any option not covered by a dedicated method, you may use option(string, mixed) or pass an array via options(array).

Background Removal (BiRefNet)

The package also handles fal-ai/birefnet, which removes the background of a single attached image and returns a transparent PNG. v2 is used by default; pass birefnet/v1 to opt into the legacy model.

A prompt string is required by the SDK but ignored by BiRefNet — use any placeholder. Per-call options the handler passes through to fal: model (Swin variant), output_format (png | webp), sync_mode.

Attachments

The driver accepts every attachment type the Laravel AI SDK exposes:

Source Behavior
ImageFile::fromUrl($url) URL is forwarded to fal verbatim.
ImageFile::fromPath($path) Bytes are read from disk and uploaded to fal storage.
ImageFile::fromBase64($data, $mime) Decoded and uploaded to fal storage.
ImageFile::fromStorage($path, $disk) Pulled from the disk and uploaded to fal storage.
ImageFile::fromUpload($uploadedFile) Read from the request and uploaded to fal storage.

When an upload is required, the package uses fal's storage upload endpoint and substitutes the returned URL into the request.

Extending With New Models

To support a fal model the package does not ship a handler for, implement the IanRodrigues\FalAi\Image\ModelHandler interface:

Register the handler in config/fal-ai.php:

Handlers are resolved in reverse registration order, so application-level handlers take precedence over the defaults the package ships.

When fal-ai.fetch_images is enabled, the gateway downloads each result URL before invoking parseResponse. The downloaded bytes are attached to each image entry under a _b64 key alongside the original url and content_type fields. Your handler should prefer _b64 when present, as shown above.

Events

The driver dispatches the SDK's own image events, so Event::fake and listener registration behave exactly as they do for the bundled providers:

Exceptions

All exceptions raised by the driver extend IanRodrigues\FalAi\Exceptions\FalException:

Exception Raised when
FalRequestException fal returned a non-2xx response, or a terminal failure status.
FalQueueTimeoutException A queued job did not complete before queue.timeout elapsed.
UnknownModelException No handler is registered for the requested model.
MissingAttachmentsException A model that requires attachments was invoked without any.

You may catch FalException to handle all driver-originated failures uniformly.

Configuration Reference

The full list of options available in config/fal-ai.php:

Key Type Default Description
key string env('FAL_KEY') Your fal API key.
base_url string https://queue.fal.run fal's queue endpoint.
sync_base_url string https://fal.run fal's synchronous endpoint. Reserved for future use.
storage_upload_url string https://rest.alpha.fal.ai/storage/upload/initiate Initiates a two-step upload: returns a presigned URL the package then PUTs the bytes to.
request_timeout int 30 Per-request timeout in seconds.
connect_timeout int 10 Connection timeout in seconds.
image_download_timeout int 30 Timeout for downloading result images when fetch_images is enabled.
queue.initial_delay_ms int 1000 Delay before the first status poll.
queue.max_delay_ms int 5000 Upper bound on the exponential polling backoff.
queue.timeout int 120 Maximum total seconds to wait for a job to complete.
fetch_images bool true When true, result image URLs are downloaded and inlined as base64. Set false to keep URLs.
image.models array [NanoBananaTwoEdit::class] Ordered list of registered ModelHandler classes.

Roadmap

The package's gateway implements fal's queue, polling, and storage-upload primitives in a capability-agnostic way. Audio, video, and transcription support will be added as fal expands its catalog under parallel namespaces (IanRodrigues\FalAi\Audio, IanRodrigues\FalAi\Video, and so on) following the same ModelHandler registry pattern documented above.

Testing

The package ships with a Pest test suite:

To run Pint against the codebase:

License

laravel-fal-ai is open-sourced software licensed under the MIT license.

All versions of laravel-fal-ai with dependencies

PHP Build Version
Package Version
Requires php Version ^8.3
illuminate/contracts Version ^12.0|^13.0
illuminate/http Version ^12.0|^13.0
illuminate/support Version ^12.0|^13.0
laravel/ai Version ^0.7
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package ianrodrigues/laravel-fal-ai contains the following files

Loading the files please wait ...