ImageResponseParser: Parse Image Generation Responses

ImageResponseParser is a static utility called by provider adapters after receiving a raw HTTP response from an OpenAI-compatible /images/generations endpoint. It normalizes the JSON payload — regardless of minor per-provider shape differences — into a typed ImageResponse that contains an array of ImageData objects, a Usage token count, the unmodified raw payload, and a providerMetadata map keyed by provider name. This normalization layer means consuming code never has to inspect raw arrays or account for field name variations between providers.

Namespace

AiSdk\OpenAICompatible\ImageResponseParser

Method

`parse()`

public static function parse(array $payload, string $providerName): ImageResponse

Deserializes an OpenAI-compatible /images/generations response payload into a structured ImageResponse.

Parameters

payload

array<string, mixed>

required

The decoded JSON body returned by the provider. The parser reads the following top-level keys:

data — array of image objects (each may contain b64_json, mime_type, media_type, width, height, and url).
usage — token count object (may use OpenAI-style or Anthropic-style key names; see Usage normalization below).
id, created, model, size, quality, output_format — optional metadata keys captured in providerMetadata.

providerName

string

required

The canonical provider name, e.g. "openai" or "openai-compatible". Used as the key under which provider-specific metadata is stored inside ImageResponse::$providerMetadata.

Return Type

parse() returns an ImageResponse with the following fields.

images

ImageData[]

Array of parsed image objects, one per item in payload['data']. Items that are not arrays are silently skipped.

Show ImageData fields

base64

string|null

Raw base64-encoded image data, sourced from b64_json in the response item. null when the item does not contain a b64_json key or when the provider returns a URL instead.

mimeType

string

The MIME type of the image. Sourced from mime_type, falling back to media_type, and finally defaulting to "image/png" when neither key is present. Common values are "image/png", "image/webp", and "image/jpeg".

width

int|null

Image width in pixels, sourced from the width integer field of the response item. null when absent or not an integer.

height

int|null

Image height in pixels, sourced from the height integer field of the response item. null when absent or not an integer.

url

string|null

Public URL to the generated image, sourced from url. null when the provider returns base64 data instead of a URL, or when the field is absent.

bytes()

string

Convenience method on ImageData that returns the raw binary bytes by base64-decoding the base64 property. Call this when you need to write the image to disk or pass it to an image-processing library.

usage

Usage

Token usage for the generation request, normalized from payload['usage']. See Usage normalization for details on how provider-specific key names are handled.

Show Usage fields

inputTokens

int

Number of tokens consumed by the input prompt. Sourced from input_tokens, falling back to prompt_tokens. Defaults to 0 when neither key is present.

outputTokens

int

Number of tokens consumed generating the image. Sourced from output_tokens, falling back to completion_tokens. Defaults to 0 when neither key is present.

totalTokens

int|null

Total token count sourced from total_tokens. null when the key is absent or is not an integer.

rawResponse

array<string, mixed>

The original $payload array, stored unmodified. Useful for logging, debugging, or accessing provider-specific fields that the parser does not extract into typed properties.

providerMetadata

array<string, array<string, mixed>>

A map keyed by $providerName. The inner array is built from the following top-level payload fields and contains only non-null values:

Key	Source	Type
`id`	`payload['id']`	string
`created`	`payload['created']`	int
`model`	`payload['model']`	string
`size`	`payload['size']`	string
`quality`	`payload['quality']`	string
`output_format`	`payload['output_format']`	string

Fields that are absent from the payload, or whose values are not the expected type, are filtered out with array_filter.

Usage Normalization

Different OpenAI-compatible providers use different key names for token counts. ImageResponseParser handles both variants transparently:

`Usage` property	Primary key	Fallback key	Default when absent
`inputTokens`	`input_tokens`	`prompt_tokens`	`0`
`outputTokens`	`output_tokens`	`completion_tokens`	`0`
`totalTokens`	`total_tokens`	(none)	`null`

inputTokens and outputTokens default to 0 rather than null so that arithmetic on Usage objects is always safe without null-checks. Only totalTokens can be null, reflecting that some providers omit it entirely.

Example

The following example mirrors the 'parses an image generation response' integration test. It shows a complete payload with all commonly populated fields and demonstrates accessing the parsed result.

use AiSdk\OpenAICompatible\ImageResponseParser;

$response = ImageResponseParser::parse(
    payload: [
        'id'      => 'img_123',
        'created' => 1710000000,
        'model'   => 'image-model',
        'size'    => '1024x1024',
        'data'    => [
            [
                'b64_json'  => base64_encode('image-bytes'),
                'mime_type' => 'image/webp',
                'width'     => 1024,
                'height'    => 1024,
            ],
        ],
        'usage' => [
            'input_tokens'  => 12,
            'output_tokens' => 8,
            'total_tokens'  => 20,
        ],
    ],
    providerName: 'openai-compatible',
);

// Access the first generated image
$image = $response->first();

$image->mimeType;   // 'image/webp'
$image->width;      // 1024
$image->height;     // 1024
$image->bytes();    // 'image-bytes'  (raw binary, base64-decoded)

// Token usage
$response->usage->inputTokens;   // 12
$response->usage->outputTokens;  // 8
$response->usage->totalTokens;   // 20

// Provider metadata (only non-null values are present)
$response->providerMetadata['openai-compatible']['id'];      // 'img_123'
$response->providerMetadata['openai-compatible']['created']; // 1710000000
$response->providerMetadata['openai-compatible']['model'];   // 'image-model'
$response->providerMetadata['openai-compatible']['size'];    // '1024x1024'

// Original raw payload always available for debugging
$response->rawResponse; // full original array

Chat

Image

Converters & Support

ImageResponseParser: Parse Image Generation Responses

Namespace

Method

`parse()`

Parameters

Return Type

Usage Normalization

Example

Build docs developers (and LLMs) love

Chat

Image

Converters & Support

Documentation Index

​Namespace

​Method

​parse()

​Parameters

​Return Type

​Usage Normalization

​Example

Build docs developers (and LLMs) love

Namespace

Method

`parse()`

Parameters

Return Type

Usage Normalization

Example