Skip to main content

Documentation Index

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

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

The aisdk/openai package supports image generation through OpenAI’s /images/generations endpoint. Use OpenAI::image() to select a model, then chain the portable builder methods to describe your request. The SDK always requests responses in b64_json format and makes the raw bytes available on the result object, so you can save, stream, or process images without handling base64 yourself.

​
Basic Example

The following example generates a single 1024×1024 image and saves it to disk: 
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();

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

​
Request Options

​
model
string
required
The image model to use. Pass an OpenAI::image(string $modelId) handle — for example OpenAI::image('gpt-image-1'), OpenAI::image('dall-e-3'), or OpenAI::image('dall-e-2').
​
prompt
string
required
A text description of the image you want to generate. Detailed, descriptive prompts generally yield better results.
​
size
string
An explicit pixel size string such as 1024x1024, 1536x1024, or 1024x1536. When set, the SDK sends it directly as the size field in the API request. Mutually exclusive with aspectRatio — if both are set, size takes precedence.
​
aspectRatio
string
A portable aspect ratio shorthand. When no explicit size is provided the SDK maps the ratio to the closest supported pixel size automatically. Supported mappings:
Aspect RatioMapped Size
1:11024x1024
3:21536x1024
16:91536x1024
2:31024x1536
9:161024x1536
Ratios not listed above throw an InvalidArgumentException.
​
count
int
The number of images to generate. Maps to the n parameter in the OpenAI API. Defaults to 1 when omitted.

​
Limitations

Seed is not supported. Passing ->seed(int $value) to an OpenAI image request throws an InvalidArgumentException before any HTTP request is made:
OpenAI image generation does not support the portable seed() option. Use providerOptions('openai', ...) if this model or endpoint adds provider-specific seed support.
Unsupported aspect ratios throw an exception. If you call ->aspectRatio('21:9') (or any ratio not in the table above) without also supplying an explicit ->size(), the SDK throws an InvalidArgumentException:
OpenAI image generation does not support aspect ratio [21:9]. Use size() or providerOptions('openai', ...).

​
Saving and Using the Output

The $result->output object wraps the first returned image. Use bytes() to get the raw binary data, or save() to write directly to a file path. 
// Get raw image bytes (returns a binary string).
$bytes = $result->output->bytes();

// Save the image to a file.
$result->output->save(__DIR__ . '/generated.png');
When you request multiple images via ->count(int $n), iterate $result->images to access each ImageData object individually: 
use AiSdk\Generate;
use AiSdk\OpenAI;

$result = Generate::image()
    ->model(OpenAI::image('gpt-image-1'))
    ->prompt('A red cube on a white background')
    ->count(3)
    ->run();

foreach ($result->images as $index => $image) {
    $image->save(__DIR__ . "/cube_{$index}.png");
}

​
Supported Image Models

All three OpenAI image models are registered in the provider with the image_generation capability.
Model IDStatusNotes
gpt-image-1StableLatest generation model, supports transparency
dall-e-3StableHigh-quality single-image generation
dall-e-2StableFaster, supports multiple images per request
You can verify image generation support on any model handle: 
use AiSdk\Capability;
use AiSdk\OpenAI;

$model = OpenAI::image('gpt-image-1');

if ($model->supports(Capability::ImageGeneration)) {
    // Safe to call Generate::image()->model($model)->...->run()
}

​
Provider-Specific Options

Some OpenAI image parameters — such as background, quality, and output_format — have no portable SDK equivalent. Pass them directly as top-level keys inside ->providerOptions('openai', [...]). The SDK merges your array over the built request body via array_replace, so provider options can add new fields or override SDK defaults. 
use AiSdk\Generate;
use AiSdk\OpenAI;

$result = Generate::image('A red cube')
    ->model(OpenAI::image('gpt-image-1'))
    ->count(2)
    ->size('1024x1024')
    ->providerOptions('openai', ['background' => 'transparent'])
    ->run();

$result->output->save(__DIR__ . '/icon.png');
Unlike text generation (which uses a raw sub-key), image provider options are merged at the top level of the request body. See the Provider Options guide for a full comparison.

Build docs developers (and LLMs) love

Get started for freeTalk to us