README

A clean abstraction layer (interfaces, DTOs, Value Objects, Collections, Exceptions) for AI image generation systems. This library serves as a foundation for various implementations such as OpenAI DALL-E, Stable Diffusion, and Midjourney, and supports advanced scenarios such as multi-image prompting, inpainting, and ControlNet.

Requirements

• PHP 8.2 or higher
• adachsoft/collection

Installation

You can install the package via Composer:

composer require adachsoft/ai-image-contract

Usage

This library provides the core contract (ImageGeneratorInterface) and the supporting data structures. It does not contain any provider-specific API implementation. You should use or build an adapter that implements this contract.

Basic Example

use AdachSoft\AiImageContract\Collections\ImageInputVoCollection;
use AdachSoft\AiImageContract\Contracts\ImageGeneratorInterface;
use AdachSoft\AiImageContract\Models\GenerationRequestDto;
use AdachSoft\AiImageContract\ValueObjects\ImageSizeVo;
use AdachSoft\AiImageContract\ValueObjects\PromptVo;

/** @var ImageGeneratorInterface $generator */
$generator = ...;

$request = new GenerationRequestDto(
    prompt: new PromptVo('A futuristic city at sunset, cyberpunk style'),
    imageInputs: new ImageInputVoCollection([]),
    size: new ImageSizeVo(1024, 1024),
    options: [
        'steps' => 30,
        'cfg_scale' => 7.5,
    ],
);

try {
    $response = $generator->generate($request);

    foreach ($response->images as $image) {
        if ($image->url !== null) {
            echo "Generated Image URL: {$image->url}\n";
        }

        if ($image->revisedPrompt !== null) {
            echo "Revised Prompt: {$image->revisedPrompt}\n";
        }
    }
} catch (\AdachSoft\AiImageContract\Exceptions\AiImageExceptionInterface $exception) {
    echo "Generation failed: {$exception->getMessage()}";
}

Advanced Usage (Image-to-Image / ControlNet)

You can pass input images to the generator using ImageInputVoCollection.

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

$imageInputs = new ImageInputVoCollection([
    new ImageInputVo(
        source: 'https://example.com/base-image.jpg',
        type: ImageInputTypeEnum::REFERENCE,
        weight: 0.8,
    ),
    new ImageInputVo(
        source: '/path/to/mask.png',
        type: ImageInputTypeEnum::MASK,
    ),
]);

Plugins (auto-discovery)

A provider package can expose an image generator plugin by implementing ImageGeneratorPluginInterface. Plugin implementations must have no required constructor arguments so a consuming discovery mechanism can instantiate them without provider-specific setup.

Declare plugins in the provider package's composer.json under the discovery key:

{
  "extra": {
    "adachsoft/ai-image-contract": {
      "plugins": {
        "xai": "AdachSoft\\AiImageXai\\XaiImagePlugin"
      }
    }
  }
}

Plugin IDs must match ^[a-z0-9]+(?:[._-][a-z0-9]+)*$, be no longer than 64 characters, and be unique across the installation. The provider package should document the parameter names accepted by each plugin in its README, such as api_key.

The contract defines the plugin declaration key and interface, but does not provide a package discovery implementation. A consuming library is responsible for discovering and instantiating declared plugins.

Pass provider-specific string parameters using PluginParametersDto:

use AdachSoft\AiImageContract\Plugins\PluginParametersDto;
use AdachSoft\AiImageXai\XaiImagePlugin;

$plugin = new XaiImagePlugin();
$generator = $plugin->create(new PluginParametersDto(['api_key' => '...']));

Upgrade 0.2 → 0.3

The following public classes have been renamed. Update references to use the new names; no class_alias compatibility aliases are provided, so the rename is a breaking change.

GeneratedImageDto Contract

GeneratedImageDto accepts a nullable url, but the model remains valid only when at least one real image source is present.

• url may be null
• b64Json may be null
• url and b64Json cannot both be null, empty, or whitespace-only

This makes the model suitable for providers returning either a remote URL or inline base64 payload.

Exceptions

All library-specific exceptions implement AiImageExceptionInterface.

• InvalidInputException for invalid request or model data
• GenerationFailedException for non-retryable generation failures
• ContentModerationException for prompt or content rejection caused by moderation or safety filters
• RetryableException for temporary failures such as rate limits, timeouts, unavailable services, and transient provider errors; it exposes a refreshTime delay hint for retries

Architecture

The library is structured into several key namespaces:

• Contracts: contains the main ImageGeneratorInterface
• Models: contains DTOs such as GenerationRequestDto, ImageResponseDto, and GeneratedImageDto
• ValueObjects: contains immutable objects such as PromptVo, ImageSizeVo, and ImageInputVo
• Collections: contains strongly typed collections based on adachsoft/collection
• Exceptions: contains standard library exceptions implementing AiImageExceptionInterface

Testing

composer test

License

The MIT License (MIT).