Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/phpaisdk/core/llms.txt

Use this file to discover all available pages before exploring further.

aisdk/core provides a clean, fluent API for image generation through Generate::image(). You attach a model that advertises Capability::ImageGeneration, describe what you want with a prompt, optionally tune dimensions and count, then call ->run() to get an ImageResult back.

​
Basic Example

use AiSdk\Generate;
use AiSdk\OpenAI;

$result = Generate::image()
    ->model(OpenAI::image('gpt-image-1'))
    ->prompt('A clean app icon for a PHP AI SDK')
    ->size('1024x1024')
    ->run();

// Save the first image directly to disk
$result->output->save(__DIR__ . '/icon.png');

​
Fluent Methods

Every method on PendingImageRequest returns $this, so calls can be chained in any order before ->run().

​
->model(ImageModelInterface $model)

Set the image model to use for this request. The model must implement ImageModelInterface and advertise Capability::ImageGeneration. You can also register a default model globally with Generate::model() and omit this call entirely. 
$result = Generate::image()
    ->model(OpenAI::image('gpt-image-1'))
    ->prompt('Sunset over mountain peaks')
    ->run();

​
->prompt(string $prompt)

The text description of the image you want to generate. This is the only required field — ->run() throws an InvalidArgumentException if the prompt is empty or whitespace-only. You can also pass the prompt directly to Generate::image() as a shorthand: 
$result = Generate::image('Sunset over mountain peaks')
    ->model(OpenAI::image('gpt-image-1'))
    ->run();

​
->count(int $count)

How many images to generate in a single request. Defaults to 1. Must be at least 1. All generated images are available on $result->images; $result->output is always the first image. 
->count(4)

​
->size(string $size)

Request a specific pixel resolution in {width}x{height} format. The value must match the pattern \d+x\d+ — for example '1024x1024', '1792x1024', or '512x512'. The provider will reject unsupported resolutions. 
->size('1792x1024')

​
->aspectRatio(string $aspectRatio)

Request a proportional aspect ratio in {width}:{height} format, such as '16:9' or '1:1'. The value must match the pattern \d+:\d+. Use this when you want a portable constraint that the provider translates to its closest native resolution. 
->aspectRatio('16:9')
->size() and ->aspectRatio() are distinct options that you can set independently or together — the provider decides how to interpret them. Use ->size() when you need an exact pixel dimension, and ->aspectRatio() when you want a portable ratio that works across providers without knowing their supported resolutions.

​
->seed(int $seed)

Pass an integer seed to the provider for reproducible outputs. Using the same prompt, model, and seed should produce the same image across calls (provider support varies). 
->seed(42)

​
->providerOptions(string $provider, array $options)

Forward provider-specific options that have no first-class equivalent in the SDK. The options are keyed by provider name and deep-merged on repeated calls. 
->providerOptions('openai', [
    'quality'  => 'hd',
    'style'    => 'vivid',
    'modality' => 'image',
])

​
Working with ImageResult

->run() returns an ImageResult value object with the following properties:
PropertyTypeDescription
$outputImageDataConvenience accessor — always the first image in the response.
$imagesImageData[]All generated images, indexed from zero.
$usageUsageToken / credit usage reported by the provider.
$rawResponsearrayThe unmodified provider response payload.
$providerMetadataarrayExtra metadata attached by the provider driver.

​
Working with ImageData

Each item in $result->images (and $result->output) is an ImageData instance:
PropertyTypeDescription
$base64?stringBase64-encoded image content, or null if the provider returned a URL instead.
$mimeTypestringMIME type of the image, e.g. 'image/png'. Defaults to 'image/png'.
$width?intWidth in pixels, if reported by the provider.
$height?intHeight in pixels, if reported by the provider.
$url?stringHosted URL returned by the provider, if available.

​
ImageData::save(string $path): string

Decodes the base64 content and writes the raw bytes to $path. Returns the path on success. Throws AiSdkException if the base64 content is missing or the file cannot be written. 
$result->output->save(__DIR__ . '/output.png');

​
ImageData::bytes(): ?string

Decodes and returns the raw binary bytes from $base64, or null if $base64 is not set. Useful when you need to store or stream the bytes yourself without touching the filesystem. 
$bytes = $result->output->bytes();
file_put_contents('output.png', $bytes);

​
Generating Multiple Images

Use ->count() to request several images at once and iterate $result->images: 
use AiSdk\Generate;
use AiSdk\OpenAI;

$result = Generate::image('Minimal line art of Lahore Fort')
    ->model(OpenAI::image('gpt-image-1'))
    ->count(4)
    ->aspectRatio('1:1')
    ->seed(7)
    ->run();

foreach ($result->images as $index => $image) {
    $path = $image->save(__DIR__ . "/fort-{$index}.png");
    echo "Saved image {$index} to {$path}" . PHP_EOL;
}

​
Provider Options Passthrough

When a provider supports settings that have no first-class SDK equivalent, use ->providerOptions(): 
use AiSdk\Generate;
use AiSdk\OpenAI;

$result = Generate::image('Abstract geometric wallpaper')
    ->model(OpenAI::image('gpt-image-1'))
    ->size('1024x1024')
    ->providerOptions('openai', ['quality' => 'hd', 'style' => 'vivid'])
    ->run();

$result->output->save(__DIR__ . '/wallpaper.png');

​
Required Capability

The SDK validates that the model advertises Capability::ImageGeneration before sending the request. If the capability is missing, a CapabilityNotSupportedException is thrown before any network call is made. 
use AiSdk\Capability;

// When registering a custom model, include ImageGeneration:
OpenAI::registerModel('my-image-model', capabilities: [
    Capability::ImageGeneration,
]);

Build docs developers (and LLMs) love

Get started for freeTalk to us