ImageRequestBuilder: Build Image Generation Bodies

ImageRequestBuilder is a static utility called by provider adapters that speak the OpenAI-compatible /images/generations wire format. It converts a portable ImageRequest — carrying prompt text, image count, optional size or aspect ratio, seed, and per-provider options — into the array<string, mixed> body that is sent directly to the endpoint. The $options array makes the builder flexible enough to serve providers that diverge slightly from OpenAI’s own parameter names, so a single class eliminates the need for per-provider builder copies.

Namespace

AiSdk\OpenAICompatible\ImageRequestBuilder

Method

`build()`

public static function build(
    string $modelId,
    string $providerName,
    ImageRequest $request,
    array $options = []
): array

Serializes an ImageRequest into an OpenAI-compatible request body. The returned array always contains model, prompt, and n. Additional keys are added depending on the $options configuration and the fields present on $request.

Parameters

modelId

string

required

The model identifier to embed in the request body as model. This is the provider-specific model string, e.g. "dall-e-3" or "grok-imagine-image-quality".

providerName

string

required

The canonical provider name, e.g. "openai" or "xai". Used to extract $request->providerOptionsFor($providerName)['raw'] for the raw escape hatch merge.

request

ImageRequest

required

The portable image generation request. The builder reads the following fields:

prompt — the text description of the image to generate.
count — number of images to generate (n).
size — explicit size string such as "1024x1024". When null and inferSizeFromAspectRatio is true, the size is derived from aspectRatio.
aspectRatio — canonical ratio string such as "16:9" or "1:1".
seed — optional integer seed for reproducible generation.
providerOptions — provider-keyed map; the ['raw'] sub-key under $providerName is merged last into the body.

options

array

default:"[]"

Configuration array that controls how the body is assembled. All keys are optional.

Show options keys

options.aspectRatioParameter

string|null

default:"null"

When set to a non-null string, the aspect ratio from $request->aspectRatio is added to the body under this key. For example, passing 'aspect_ratio' results in 'aspect_ratio' => '16:9' in the body. When null (the default), no aspect ratio key is written.

options.inferSizeFromAspectRatio

bool

default:"true"

When true and $request->size is null, the builder calls the internal sizeFromAspectRatio() helper to derive a canonical WIDTHxHEIGHT string from $request->aspectRatio. Set to false for providers that accept an aspect ratio parameter directly and do not need a size field.

options.includeResponseFormat

bool

default:"true"

When true, adds 'response_format' => 'b64_json' to the body so the provider returns base64-encoded image data rather than a URL. Set to false for providers that do not recognise this parameter or always return URLs.

options.sizeParameter

string|null

default:"'size'"

The key under which the resolved size string is written. Defaults to 'size' (standard OpenAI). Pass a different string to rename the field for providers that use a different parameter name. Pass null to omit the size field entirely.

options.seedParameter

string|null

default:"'seed'"

The key under which $request->seed is written when it is non-null. Defaults to 'seed'. Pass null to omit the seed field even when a seed is present on the request.

Request Body Keys

Key	Always present	Description
`model`	✅	Value of `$modelId`
`prompt`	✅	Value of `$request->prompt`
`n`	✅	Value of `$request->count`
`response_format`	When `includeResponseFormat` is `true` (default)	Fixed value `"b64_json"`
`size` / custom	When `sizeParameter` is non-null and a size can be resolved	Resolved size string
`aspect_ratio` / custom	When `aspectRatioParameter` is non-null and `$request->aspectRatio` is non-null	The aspect ratio string
`seed` / custom	When `seedParameter` is non-null and `$request->seed` is non-null	The integer seed
(raw keys)	When `providerOptions` contains a `raw` array for the provider	Merged last, can override any key above

Aspect Ratio → Size Mapping

When inferSizeFromAspectRatio is true and no explicit size is set, the builder maps $request->aspectRatio to a fixed pixel dimension string using the following table:

Aspect ratio	Resolved size
`1:1`	`1024x1024`
`3:2`	`1536x1024`
`16:9`	`1536x1024`
`2:3`	`1024x1536`
`9:16`	`1024x1536`

Aspect ratios that are not in the table above — such as "21:9" or "4:3" — cause sizeFromAspectRatio() to throw an \AiSdk\Exceptions\InvalidArgumentException. Either pass an explicit size() on the request, use providerOptions() with a raw override, or set inferSizeFromAspectRatio => false and handle sizing yourself via aspectRatioParameter.

Raw Escape Hatch

Any array stored under $request->providerOptionsFor($providerName)['raw'] is merged into the body last using array_replace. This means raw keys can override any key that the builder itself wrote, giving you full control over the final payload without subclassing or forking the builder.

Use the raw escape hatch sparingly — for provider-specific parameters that have no portable equivalent. Common cases are background transparency hints, output resolution tiers, or style presets.

Examples

1 — Basic call with an explicit size

This example is drawn from the wire-format integration test. It passes an explicit size and uses the raw escape hatch to add a provider-specific background parameter.

use AiSdk\OpenAICompatible\ImageRequestBuilder;
use AiSdk\Requests\ImageRequest;

$body = ImageRequestBuilder::build(
    'image-model',
    'openai-compatible',
    new ImageRequest(
        prompt: 'A clean product photo',
        count: 2,
        size: '1024x1024',
        providerOptions: [
            'openai-compatible' => [
                'raw' => ['background' => 'transparent'],
            ],
        ],
    ),
);

// $body is:
// [
//     'model'           => 'image-model',
//     'prompt'          => 'A clean product photo',
//     'n'               => 2,
//     'response_format' => 'b64_json',
//     'size'            => '1024x1024',
//     'background'      => 'transparent',   // merged from raw
// ]

2 — Aspect ratio inference (16:9 → 1536x1024)

When size is omitted, the builder derives it automatically from aspectRatio. This keeps provider adapters free of hard-coded dimension strings.

use AiSdk\OpenAICompatible\ImageRequestBuilder;
use AiSdk\Requests\ImageRequest;

$body = ImageRequestBuilder::build(
    'image-model',
    'provider',
    new ImageRequest(
        prompt: 'A tiny house',
        count: 2,
        aspectRatio: '16:9',
    ),
);

// $body['size'] === '1536x1024'
// $body is:
// [
//     'model'           => 'image-model',
//     'prompt'          => 'A tiny house',
//     'n'               => 2,
//     'response_format' => 'b64_json',
//     'size'            => '1536x1024',
// ]

3 — Provider-specific variant with `aspect_ratio` parameter and no `size`

Some providers — such as xAI’s image models — accept an aspect_ratio key directly and do not want a size field at all. Pass aspectRatioParameter, disable inferSizeFromAspectRatio, and set sizeParameter to null.

use AiSdk\OpenAICompatible\ImageRequestBuilder;
use AiSdk\Requests\ImageRequest;

$body = ImageRequestBuilder::build(
    'grok-imagine-image-quality',
    'xai',
    new ImageRequest(
        prompt: 'A city skyline',
        count: 1,
        aspectRatio: '16:9',
        providerOptions: [
            'xai' => ['raw' => ['resolution' => '2k']],
        ],
    ),
    [
        'aspectRatioParameter'    => 'aspect_ratio',
        'inferSizeFromAspectRatio' => false,
        'sizeParameter'           => null,
    ],
);

// $body is:
// [
//     'model'           => 'grok-imagine-image-quality',
//     'prompt'          => 'A city skyline',
//     'n'               => 1,
//     'response_format' => 'b64_json',
//     'aspect_ratio'    => '16:9',
//     'resolution'      => '2k',   // merged from raw
// ]
// Note: 'size' key is absent entirely.

Chat

Image

Converters & Support

ImageRequestBuilder: Build Image Generation Bodies

Namespace

Method

`build()`

Parameters

Request Body Keys

Aspect Ratio → Size Mapping

Raw Escape Hatch

Examples

1 — Basic call with an explicit size

2 — Aspect ratio inference (16:9 → 1536x1024)

3 — Provider-specific variant with `aspect_ratio` parameter and no `size`

Build docs developers (and LLMs) love

Chat

Image

Converters & Support

Documentation Index

​Namespace

​Method

​build()

​Parameters

​Request Body Keys

​Aspect Ratio → Size Mapping

​Raw Escape Hatch

​Examples

​1 — Basic call with an explicit size

​2 — Aspect ratio inference (16:9 → 1536x1024)

​3 — Provider-specific variant with aspect_ratio parameter and no size

Build docs developers (and LLMs) love

Namespace

Method

`build()`

Parameters

Request Body Keys

Aspect Ratio → Size Mapping

Raw Escape Hatch

Examples

1 — Basic call with an explicit size

2 — Aspect ratio inference (16:9 → 1536x1024)

3 — Provider-specific variant with `aspect_ratio` parameter and no `size`