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 (e.g., OpenAI DALL-E, Stable Diffusion, 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 necessary data structures. It does not contain any specific API implementation. You should use or create an adapter that implements this contract.

Basic Example

use AdachSoft\AiImageContract\Contracts\ImageGeneratorInterface;
use AdachSoft\AiImageContract\Models\GenerationRequest;
use AdachSoft\AiImageContract\ValueObjects\Prompt;
use AdachSoft\AiImageContract\ValueObjects\ImageSize;
use AdachSoft\AiImageContract\Collections\ImageInputCollection;

/** @var ImageGeneratorInterface $generator */
$generator = ... // Instantiate your specific implementation

$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) {
        echo "Generated Image URL: " . $image->url . "\n";
        if ($image->revisedPrompt) {
            echo "Revised Prompt: " . $image->revisedPrompt . "\n";
        }
    }
} catch (\AdachSoft\AiImageContract\Exceptions\AiImageExceptionInterface $e) {
    echo "Generation failed: " . $e->getMessage();
}

Advanced Usage (Image-to-Image / ControlNet)

You can pass input images to the generator using the ImageInputCollection.

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

$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
    )
]);

$request = new GenerationRequest(
    prompt: new Prompt('Add a red car to the street'),
    imageInputs: $imageInputs
);

Architecture

The library is structured into several key namespaces:

Contracts: Contains the main ImageGeneratorInterface.
Models: Contains DTOs like GenerationRequest, ImageResponse, and GeneratedImage.
ValueObjects: Contains immutable objects like Prompt, ImageSize, and ImageInput.
Collections: Contains strongly-typed collections (GeneratedImageCollection, ImageInputCollection) based on adachsoft/collection.
Exceptions: Contains standard exceptions (GenerationFailedException, InvalidInputException) implementing AiImageExceptionInterface.

Testing

composer test

License

The MIT License (MIT).

adachsoft / ai-image-contract

Maintainers

Package info

Statistics

Security