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\ImageInputCollection;
use AdachSoft\AiImageContract\Contracts\ImageGeneratorInterface;
use AdachSoft\AiImageContract\Models\GenerationRequest;
use AdachSoft\AiImageContract\ValueObjects\ImageSize;
use AdachSoft\AiImageContract\ValueObjects\Prompt;

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

$request = new GenerationRequest(
    prompt: new Prompt('A futuristic city at sunset, cyberpunk style'),
    imageInputs: new ImageInputCollection([]),
    size: new ImageSize(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 ImageInputCollection.

use AdachSoft\AiImageContract\Collections\ImageInputCollection;
use AdachSoft\AiImageContract\Models\Enums\ImageInputTypeEnum;
use AdachSoft\AiImageContract\ValueObjects\ImageInput;

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

GeneratedImage Contract

GeneratedImage 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 GenerationRequest, ImageResponse, and GeneratedImage
• ValueObjects: contains immutable objects such as Prompt, ImageSize, and ImageInput
• Collections: contains strongly typed collections based on adachsoft/collection
• Exceptions: contains standard library exceptions implementing AiImageExceptionInterface

Testing

composer test

License

The MIT License (MIT).