Skip to content

Image generation

Generate images with Laravel AI's Image API and the models Cloudflare hosts, with reference images on FLUX.2.

Updated

The package adds Workers AI to Laravel AI’s Image API. It needs no extra config and works on the direct route and the gateway route.

To send an image to a chat model instead, see Image input.

Generate an image

use Laravel\Ai\Image;

$image = Image::of('A green apple on a wooden table.')
    ->landscape()
    ->quality('medium')
    ->generate(provider: 'workers-ai');

$path = $image->store('images', 'public');

$bytes = (string) $image;
$mime = $image->images->first()->mime;

Size and quality

Method Sends
square() 1024 x 1024
portrait() 832 x 1248
landscape() 1248 x 832
size('512x384') The width and height you give
quality('low') 4 inference steps
quality('medium') 8 inference steps
quality('high') 20 inference steps

With no size or quality, Cloudflare uses the model’s defaults. More steps take longer and cost more. flux-1-schnell allows at most 8 steps, so the package caps it there.

Choose a model

The default is @cf/black-forest-labs/flux-2-klein-4b. To change it, set models.image.default on the provider entry in config/ai.php, or pass model: to generate(). Each model has its own limits; see the Cloudflare model catalog.

Model Size Reference images
@cf/black-forest-labs/flux-2-klein-4b, flux-2-klein-9b, flux-2-dev Yes Yes
@cf/black-forest-labs/flux-1-schnell No. A size throws. No
@cf/bytedance/stable-diffusion-xl-lightning, @cf/stabilityai/stable-diffusion-xl-base-1.0, @cf/lykon/dreamshaper-8-lcm Yes No
@cf/leonardo/lucid-origin, @cf/leonardo/phoenix-1.0 Yes No

To use a model’s other inputs, add them with withProviderOptions(), which needs laravel/ai 1.0 or later.

Image::of('A green apple.')
    ->withProviderOptions(['seed' => 42])
    ->generate(provider: 'workers-ai');

Use reference images

FLUX.2 models take up to 4 reference images, which Cloudflare says must each be smaller than 512 x 512. In the prompt, refer to them by position, starting at 0, or in plain words.

use Laravel\Ai\Files\Image as ImageFile;

$image = Image::of('Take the subject of image 1 and style it like image 0.')
    ->attachments([
        ImageFile::fromPath(storage_path('app/style.png')),
        ImageFile::fromPath(storage_path('app/subject.png')),
    ])
    ->generate(provider: 'workers-ai');

A fifth image throws before the request is sent, and so does an attachment on a model that doesn’t take reference images.

Omit the provider name

Laravel AI’s default_for_images is gemini until you change it. Set it in config/ai.php to leave out provider::

'default_for_images' => 'workers-ai',

FLUX.2 and AI Gateway

FLUX.2 models send a multipart form instead of JSON, so with a gateway they use the gateway’s own URL. On an authenticated gateway they need gateway_token, on both the gateway route and the header route. Other image models need only key. See Non-JSON models.

Errors

Cloudflare’s content filter can reject a prompt with 400 Input prompt contains NSFW content, and it sometimes flags harmless ones. In tests on 2026-11-05, it rejected “A green apple on a wooden table.” on phoenix-1.0 in 3 of 8 runs, while the same prompt passed on the other models tested. Try again, reword the prompt, or use another model.

Test your code

use Laravel\Ai\Image;

Image::fake();

// run your code, then:
Image::assertGenerated(fn ($prompt) => $prompt->contains('apple'));

Cost

Cloudflare bills images in neurons. In a test on 2026-11-05, one flux-1-schnell image at 1 step cost 57.6 neurons. The package reports the figure with the WorkersAiUsageReported event. See Cost tracking.

Type to search…

↑↓ navigate↵ selectEsc close