adachsoft / ai-image-google

v0.1.0 2026-11-09 13:21 UTC

Requires

• php: ^8.3
• ext-curl: *
• ext-fileinfo: *
• adachsoft/ai-image-contract: ^0.3
• guzzlehttp/guzzle: ^8.3

Requires (Dev)

• adachsoft/php-code-style: ^0.7.2
• friendsofphp/php-cs-fixer: ^3.95
• phpstan/phpstan: ^2.3
• phpunit/phpunit: ^12.5
• rector/rector: ^2.8
• symplify/phpstan-rules: ^14.19
• vlucas/phpdotenv: ^5.8

MIT

• Arkadiusz Adach

• google
• ai
• Gemini
• image-generation
• adachsoft
• image-provider

Published on Packagist.org on 2026-11-09 13:37 UTC

README

A PHP 8.3+ image-generation provider for adachsoft/ai-image-contract. It uses Google's Gemini Interactions API and returns the contract's ImageResponseDto and GeneratedImageDto values.

Installation

composer require adachsoft/ai-image-google

The package requires the ext-curl and ext-fileinfo PHP extensions. It registers the provider in Composer metadata under the adachsoft/ai-image-contract discovery key with the name google:

{
  "adachsoft/ai-image-contract": {
    "plugins": {
      "google": "AdachSoft\\AiImageGoogle\\Plugin\\GoogleImageGeneratorPlugin"
    }
  }
}

The plugin has a no-argument constructor for discovery. Its create() method receives the API key explicitly; production classes do not read .env files or environment variables.

Creating a generator

Pass api_key as a required plugin parameter. model is optional and defaults to gemini-nano-banana-2.1.

use AdachSoft\AiImageContract\Collections\ImageInputVoCollection;
use AdachSoft\AiImageContract\Models\GenerationRequestDto;
use AdachSoft\AiImageContract\Plugins\PluginParametersDto;
use AdachSoft\AiImageContract\ValueObjects\PromptVo;
use AdachSoft\AiImageGoogle\Plugin\GoogleImageGeneratorPlugin;

$apiKey = /* retrieve this value from your application's secret store */;
$plugin = new GoogleImageGeneratorPlugin();
$generator = $plugin->create(new PluginParametersDto([
    'api_key' => $apiKey,
    // 'model' => 'gemini-3.1-flash-image',
]));

$response = $generator->generate(new GenerationRequestDto(
    new PromptVo('A watercolor illustration of a small garden.'),
    new ImageInputVoCollection([]),
    options: ['aspect_ratio' => '1:1', 'image_size' => '1K'],
));

$firstImage = $response->images->get(0);

Reference images

Provide images in an ImageInputVoCollection with type REFERENCE. Sources may be:

• a publicly accessible https:// URL;
• a local image path;
• raw standard base64 image data;
• a data:<mime>;base64,<data> URI.

use AdachSoft\AiImageContract\Collections\ImageInputVoCollection;
use AdachSoft\AiImageContract\Models\Enums\ImageInputTypeEnum;
use AdachSoft\AiImageContract\Models\GenerationRequestDto;
use AdachSoft\AiImageContract\ValueObjects\ImageInputVo;
use AdachSoft\AiImageContract\ValueObjects\PromptVo;

$editRequest = new GenerationRequestDto(
    new PromptVo('Add a small green leaf to the reference image.'),
    new ImageInputVoCollection([
        new ImageInputVo('/path/to/reference.png', ImageInputTypeEnum::REFERENCE),
    ]),
);
$editedResponse = $generator->generate($editRequest);

Local files are read by the provider and their bytes are sent inline to Google. For HTTPS sources, Google fetches the URL; PHP does not download it. Use only data that you are authorized to disclose to Google, and avoid URLs containing sensitive query parameters. Inline local files are limited to 15,000,000 bytes, and the serialized request is limited to 20,000,000 bytes.

Options and dimensions

The following native options are supported:

• aspect_ratio: one of 1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, or 21:9;
• image_size: one of 512, 1K, 2K, or 4K;
• seed: an integer.

aspect_ratio and image_size are sent in response_format; seed is sent in generation_config. Google validates whether an option combination is supported by the selected model. Unknown options and invalid values are rejected. options must be an associative map or an empty array.

When GenerationRequestDto::size is provided, dimensions must exactly match a documented model size. The provider does not round or silently alter dimensions. Do not combine size with the aspect_ratio or image_size options.

gemini-nano-banana-2.1 and gemini-3.1-flash-image

The following dimensions are the 1K values. 2K and 4K multiply both dimensions by two and four, respectively. gemini-3.1-flash-image also supports 512, which divides both dimensions by two; gemini-nano-banana-2.1 does not support that level.

Aspect ratio	1K dimensions
1:1	1024 × 1024
1:4	512 × 2048
1:8	384 × 3072
2:3	848 × 1264
3:2	1264 × 848
3:4	896 × 1200
4:1	2048 × 512
4:3	1200 × 896
4:5	928 × 1152
5:4	1152 × 928
8:1	3072 × 384
9:16	768 × 1376
16:9	1376 × 768
21:9	1584 × 672

gemini-3-pro-image

Supports the same 1K, 2K, and 4K dimensions as the table above, except for aspect ratios 1:4, 1:8, 4:1, and 8:1.

gemini-2.5-flash-image

This model supports only the exact dimensions below. The provider sends aspect_ratio and does not send image_size for these dimensions.

Aspect ratio	Dimensions
1:1	1024 × 1024
2:3	832 × 1248
3:2	1248 × 832
3:4	864 × 1184
4:3	1184 × 864
4:5	896 × 1152
5:4	1152 × 896
9:16	768 × 1344
16:9	1344 × 768
21:9	1536 × 672

Other models, including gemini-3.1-flash-lite-image, may be used without size and with native options, but exact size is rejected because this provider has no documented dimension table for them.

Unsupported contract inputs

Google's adapter does not silently ignore or rewrite contract data that it cannot represent natively. It rejects:

• any non-null negativePrompt;
• MASK, STYLE, or POSE image inputs;
• reference image weights other than 1.0;
• unknown plugin parameters and generation options;
• unsupported or non-exact dimensions.

A consumer may describe style or pose in its own prompt and may provide the corresponding image as a REFERENCE.

Errors and request behavior

The provider maps contract validation failures to InvalidInputException, recognized moderation rejections to ContentModerationException, transient connection failures and HTTP 408, 429, 500, 502, 503, and 504 responses to RetryableException, and other API or response failures to GenerationFailedException. A retryable response uses a valid Retry-After delta in seconds or defaults to 30 seconds. The provider does not retry automatically; retry decisions remain with the consumer.

Requests use HTTPS with TLS verification, a 10-second connection timeout, a 180-second total timeout, and no HTTP redirects. The Google API key is sent in the x-goog-api-key header. Prompts, images, API keys, and raw Google response bodies are not included in provider exception messages.

Examples

• Generate an image.
• Edit an image using a reference.

Real API test

The production test performs two real Google requests: it generates an image and then sends that image back as a REFERENCE for an edit. This can incur the cost of two image-generation requests.

Set GOOGLE_IMAGE_E2E_API_KEY in the package-root .env file using .env.example as a template, or provide it through $_ENV, then run:

vendor/bin/phpunit --group production

The test is skipped when the key is absent. Unit tests use synthetic responses and do not contact Google.