PHP Prisma

Light-weight PHP package for integrating multi-media related Large Language Models (LLMs) into your applications using a unified interface.

Supported providers

Audio

  demix denoise describe revoice speak transcribe
AudioPod yes yes - yes yes yes
Deepgram - - - - yes yes
ElevenLabs - - - yes yes yes
Gemini - - yes - - -
Groq - - yes - yes yes
Mistral - - yes - - yes
Murf - - - yes yes -
OpenAI - - yes - yes yes

Image

  background describe detext erase imagine inpaint isolate recognize relocate repaint uncrop upscale vectorize
Bedrock Titan - - - - yes yes yes - - - - - yes
Black Forest Labs - - - - beta beta - - - - beta - -
Clipdrop yes - yes yes yes - yes - - - yes yes -
Cohere - - - - - - - - - - - - yes
Gemini - yes - - yes - - - - yes - - -
Groq - yes - - - - - - - - - - -
Ideogram beta beta - - beta beta - - - beta - beta -
Mistral - - - - - - - yes - - - - -
OpenAI - yes - - yes yes - - - - - - -
RemoveBG - - - - - - yes - yes - - - -
StabilityAI - - - yes yes yes yes - - - yes yes -
VertexAI - - - - yes yes - - - - - yes yes
VoyageAI - - - - - - - - - - - - yes

Video

  describe
Gemini yes

Installation

composer req aimeos/prisma

API usage

Basic usage:

use Aimeos\Prisma\Prisma;

$image = Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->model( '<modelname>' ) // if model can be selected
    ->ensure( 'imagine' ) // make sure interface is implemented
    ->imagine( 'a grumpy cat' )
    ->binary();

ensure

Ensures that the provider has implemented the method.

public function ensure( string $method ) : self

Example:

\Aimeos\Prisma\Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->ensure( 'imagine' );

has

Tests if the provider has implemented the method.

public function has( string $method ) : bool

Example:

\Aimeos\Prisma\Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->has( 'imagine' );

model

Use the model passed by its name.

Used if the provider supports more than one model and allows to select between the different models. Otherwise, it’s ignored.

public function model( ?string $model ) : self

Example:

\Aimeos\Prisma\Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->model( 'dall-e-3' );

withClientOptions

Add options for the Guzzle HTTP client.

public function withClientOptions( array `$options` ) : self

Example:

\Aimeos\Prisma\Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->withClientOptions( ['timeout' => 120] );

withSystemPrompt

Add a system prompt for the LLM.

It may be used by providers supporting system prompts. Otherwise, it’s ignored.

public function withSystemPrompt( ?string $prompt ) : self

Example:

\Aimeos\Prisma\Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->withSystemPrompt( 'You are a professional illustrator' );

Response objects

The methods return a FileResponse, TextResponse or VectorResponse object that contains the returned data with optional meta/usage/description information.

FileResponse objects:

$base64 = $response->base64(); // first base64 data, from binary, base64 and URL, waits for async requests
$file = $response->binary(); // first binary data, from binary, base64 and URL, waits for async requests
$url = $response->url(); // first URL, only if URLs are returned, otherwise NULL
$mime = $response->mimetype(); // image mime type, waits for async requests
$text = $response->description(); // image description if returned by provider
$bool = $response->ready(); // FALSE for async APIs until file is available
$file = $response->first(); // first available file object
$array = $response->files(); // all available file objects

// loop over all available files
foreach( $response as $name => $file ) {
    $file->binary()
}

URLs are automatically converted to binary and base64 data if requested and conversion between binary and base64 data is done on request too.

TextResponse objects:

$text = $response->text(); // first text content (non-streaming)
$text = $response->first(); // first available text
$texts = $response->texts(); // all texts (non-streaming)

// loop over all available texts
foreach( $response as $text ) {
    echo $text;
}

VectorResponse objects:

$vector = $response->first(); // first embedding vector if only one file has been passed
$vectors = $response->vectors(); // embedding vectors for the passed files in the same order

// loop over all available vectors
foreach( $response as $vector ) {
    print_r( $vector );
}

Included meta data (optional):

$meta = $response->meta();

It returns an associative array whose content totally depends on the provider.

Included usage data (optional):

$usage = $response->usage();

It returns an associative array whose content depends on the provider. If the provider returns usage information, the used array key is available and contains a number. What the number represents depdends on the provider too.

Audio API

demix

Separate an audio file into its individual tracks.

public function demix( Audio $audio, int $stems, array $options = [] ) : FileResponse

Supported options:

denoise

Remove noise from an audio file.

public function denoise( Audio $audio, array $options = [] ) : FileResponse

Supported options:

describe

Describe the content of an audio file.

public function describe( Audio $audio, ?string $lang = null, array $options = [] ) : TextResponse

Supported options:

revoice

Exchange the voice in an audio file.

public function revoice( Audio $audio, string $voice, array $options = [] ) : FileResponse;

Supported options:

speak

Converts text to speech.

public function speak( string $text, string $voice = , array $options = [] ) : FileResponse;

Supported options:

transcribe

Converts speech to text.

public function transcribe( Audio $audio, ?string $lang = null, array $options = [] ) : TextResponse

Supported options:

Image API

Most methods require an image object as input which contains a reference to the image that should be processed. This object can be created by:

use \Aimeos\Prisma\Files\Image;

$image = Image::fromUrl( 'https://example.com/image.php', 'image/png' );
$image = Image::fromLocalPath( 'path/to/image.png', 'image/png' );
$image = Image::fromBinary( 'PNG...', 'image/png' );
$image = Image::fromBase64( 'UE5H...', 'image/png' );

// Laravel only:
$image = Image::fromStoragePath( 'path/to/image.png', 'public', 'image/png' );

The last parameter of all methods (mime type) is optional. If it’s not passed, the file content will be retrieved to determine the mime type if reqested.

Note: It’s best to use fromUrl() if possible because all other formats (binary and base64) can be derived from the URL content but URLs can’t be created from binary/base64 data.

background

Replace image background with a background described by the prompt.

public function background( Image $image, string $prompt, array $options = [] ) : FileResponse

Supported options:

Example:

use Aimeos\Prisma\Prisma;
use \Aimeos\Prisma\Files\Image;

$image = Image::fromUrl( 'https://example.com/image.png' );

$fileResponse = Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->background( $image, 'Golden sunset on a caribbean beach' );

$image = $fileResponse->binary();

describe

Describe the content of an image.

public function describe( Image $image, ?string $lang = null, array $options = [] ) : TextResponse

Supported options:

Example:

use Aimeos\Prisma\Prisma;
use \Aimeos\Prisma\Files\Image;

$image = Image::fromUrl( 'https://example.com/image.png' );

$textResponse = Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->describe( $image, 'de' );

$text = $textResponse->text();

detext

Remove all text from the image.

public function detext( Image $image, array $options = [] ) : FileResponse

Supported options:

Example:

use Aimeos\Prisma\Prisma;
use \Aimeos\Prisma\Files\Image;

$image = Image::fromUrl( 'https://example.com/image.png' );

$fileResponse = Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->detext( `$image` );

$image = $fileResponse->binary();

erase

Erase parts of the image.

public function erase( Image $image, Image $mask, array $options = [] ) : FileResponse

The mask must be an image with black parts (#000000) to keep and white parts (#FFFFFF) to remove.

Supported options:

Example:

use Aimeos\Prisma\Prisma;
use \Aimeos\Prisma\Files\Image;

$image = Image::fromUrl( 'https://example.com/image.png' );
$mask = Image::fromBinary( 'PNG...' );

$fileResponse = Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->erase( $image, $mask );

$image = $fileResponse->binary();

imagine

Generate an image from the prompt.

public function imagine( string $prompt, array $images = [], array $options = [] ) : FileResponse

Supported options:

Example:

use Aimeos\Prisma\Prisma;

$fileResponse = Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->imagine( 'Futuristic robot looking at a dashboard' );

$image = $fileResponse->binary();

inpaint

Edit an image by inpainting an area defined by a mask according to a prompt.

public function inpaint( Image $image, Image $mask, string $prompt, array $options = [] ) : FileResponse

The mask must be an image with black parts (#000000) to keep and white parts (#FFFFFF) to edit.

Supported options:

Example:

use Aimeos\Prisma\Prisma;
use \Aimeos\Prisma\Files\Image;

$image = Image::fromUrl( 'https://example.com/image.png' );
$mask = Image::fromBinary( 'PNG...' );

$fileResponse = Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->inpaint( $image, $mask, 'add a pink flamingo' );

$image = $fileResponse->binary();

isolate

Remove the image background.

public function isolate( Image $image, array $options = [] ) : FileResponse

Supported options:

Example:

use Aimeos\Prisma\Prisma;
use \Aimeos\Prisma\Files\Image;

$image = Image::fromUrl( 'https://example.com/image.png' );

$fileResponse = Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->isolate( `$image` );

$image = $fileResponse->binary();

recognize

Recognizes the text in the given image (OCR).

public function recognize( Image $image, array $options = [] ) : TextResponse;

Supported options:

Example:

use Aimeos\Prisma\Prisma;
use \Aimeos\Prisma\Files\Image;

$image = Image::fromUrl( 'https://example.com/image.png' );

$textTesponse = Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->recognize( `$image` );

$text = $textResponse->text();

relocate

Place the foreground object on a new background.

public function relocate( Image $image, Image $bgimage, array $options = [] ) : FileResponse

Supported options:

Example:

use Aimeos\Prisma\Prisma;
use \Aimeos\Prisma\Files\Image;

$image = Image::fromUrl( 'https://example.com/image.png' );
$bgimage = Image::fromUrl( 'https://example.com/background.png' );

$fileResponse = Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->relocate( $image, $bgimage );

$image = $fileResponse->binary();

repaint

Repaint an image according to the prompt.

public function repaint( Image $image, string $prompt, array $options = [] ) : FileResponse

Supported options:

Example:

use Aimeos\Prisma\Prisma;
use \Aimeos\Prisma\Files\Image;

$image = Image::fromUrl( 'https://example.com/image.png' );

$fileResponse = Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->repaint( $image, 'Use a van Goch style' );

$image = $fileResponse->binary();

uncrop

Extend/outpaint the image.

public function uncrop( Image $image,  int $top, int $right, int $bottom, int $left, array $options = [] ) : FileResponse

Supported options:

Example:

use Aimeos\Prisma\Prisma;
use \Aimeos\Prisma\Files\Image;

$image = Image::fromUrl( 'https://example.com/image.png' );

$fileResponse = Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->uncrop( $image, 100, 200, 0, 50 );

$image = $fileResponse->binary();

upscale

Scale up the image.

public function upscale( Image $image, int $factor, array $options = [] ) : FileResponse

Supported options:

Example:

use Aimeos\Prisma\Prisma;
use \Aimeos\Prisma\Files\Image;

$image = Image::fromUrl( 'https://example.com/image.png' );

$fileResponse = Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->upscale( $image, 4 );

$image = $fileResponse->binary();

vectorize

Creates embedding vectors of the images’ content.

public function vectorize( array $images, ?int $size = null, array $options = [] ) : VectorResponse

Supported options:

Example:

use Aimeos\Prisma\Prisma;
use \Aimeos\Prisma\Files\Image;

$images = [
    Image::fromUrl( 'https://example.com/image.png' ),
    Image::fromUrl( 'https://example.com/image2.png' ),
];

$vectorResponse = Prisma::image()
    ->using( '<provider>', ['api_key' => 'xxx'])
    ->vectorize( $images, 512 );

$vectors = $vectorResponse->vectors();

Video API

describe

Describe the content of a video file.

public function describe( Video $video, ?string $lang = null, array $options = [] ) : TextResponse

Supported options:

Custom providers

Base skeleton

<?php

// for Audio providers
namespace Aimeos\Prisma\Providers\Audio;
// for Image providers
namespace Aimeos\Prisma\Providers\Image;
// for Video providers
namespace Aimeos\Prisma\Providers\Video;

use Aimeos\Prisma\Exceptions\PrismaException;
use Aimeos\Prisma\Providers\Base;


class Myprovider extends Base implements ...
{
    public function __construct( array $config )
    {
        if( !isset( $config['api_key'] ) ) {
            throw new PrismaException( sprintf( 'No API key' ) );
        }

        // if authentication is done via headers
        $this->header( '<api key name>', $config['api_key'] );
        // base url for all requests (no paths)
        $this->baseUrl( '<provider URL>' );
    }

Depending on the provider type (Audio, Image or Video), you can implement one or more of the available interfaces for that provider type:

For example:

namespace Aimeos\Prisma\Providers\Image;

use Aimeos\Prisma\Contracts\Image\Describe;
use Aimeos\Prisma\Exceptions\PrismaException;
use Aimeos\Prisma\Files\Image;
use Aimeos\Prisma\Providers\Base;
use Aimeos\Prisma\Responses\TextResponse;


class Myprovider extends Base implements Describe
{
    public function describe( Image $image, ?string $lang = null, array $options = [] ) : TextResponse
    {
        // ...
    }
}

Requests

There are a few support methods available to simplify building requests which are sent by the Guzzle client to the server of the AI provider.

First, you should validate and limit the passed options to the ones supported by the AI API. The allow() and sanitze() methods filter out unsupported values because different APIs have different parameters but users of the Prisma API should be able to pass parameters for several AI providers at once. Therefore, get only supported parameters and values using:

// filter key/value pairs in $options and use the ones allowed by the API
$allowed = $this->allow( $options, ['<key1>', '<key2>', /* ... */] );

// filter values to pass only allowed option values (optional)
$allowed = $this->sanitize( $allowed, ['<key1>' => ['<val1>', '<val2>', '<val3>']])

If the user can choose between several LLM models when using the API, the modelName() method will return the users choice or the passed default value:

$model = $this->modelName( 'gemini-2.5-flash' );

To build the request in the correct format (form key/value pairs, multipart or JSON data), the request() method transforms parameters and files for form and multipart requests. JSON data is specific to the API and you must create it yourself:

// Form data request
$data = $this->request( params );
// Multipart request
$data = ['multipart' => $this->request( params, ['image_key' = $image->binary()] )];
// JSON request
$data = ['json' => ['image_key' = array_map( fn( $image ) => $image->base64()] + params];

Then, you can send the request using the Guzzle client, validate the response and get the returned content:

// use Guzzle to send the request and get the response from the server
$response = $this->client()->post( 'relative/api/path', $data );

// validates HTTP status codes, overwrite if needed
$this->validate( $response );

// get binary content or JSON content
$content = $response->getBody()->getContents();

A full example would be:

use Aimeos\Prisma\Files\Image;
use Aimeos\Prisma\Responses\TextResponse;

public function describe( Image $image, ?string $lang = null, array $options = [] ) : TextResponse
{
    $model = $this->modelName( 'flash' );
    $allowed = $this->allow( $options, ['version'] );

    $params = ['language' => $lang] + $allowed;
    $data = ['multipart' => $this->request( params, ['file' = $image->binary()] )];
    $response = $this->client()->post( 'relative/api/path', $data );

    $this->validate( $response );

    $content = $response->getBody()->getContents();
    // return a response
}

Responses

There are several response types available, which can be returned depending on the implemented interfaces:

File response

A FileResponse can contain one or more files, either as binary or base64 data, or as remote URL. Passing the mime type is optional but prevents guessing the file type later:

use Aimeos\Prisma\Responses\FileResponse;

$response = FileResponse::fromBinary( '...', 'image/png' );
$response = FileResponse::fromBase64( '...', 'image/png' );
$response = FileResponse::fromUrl( '...', 'image/png' );

You can also add more than one file by using the add() method:

use Aimeos\Prisma\Files\File;

$response->add( File::fromBinary( '...', 'image/png' ) );

If the API processes requests asynchronously, the fromAsync() method accepts a closure function and the optional timeout between requests as second parameter:

$client = $this->client();
$response = FileResponse::fromAsync( function( FileResponse $fr ) uses ( $client ) {
    // download or add file(s) to file response object
    $fr->add( File::fromUrl( '...', 'image/png' ) );
}, 3 );

Text response

The TextResponse can contain one or more texts and is created by using:

use Aimeos\Prisma\Responses\TextResponse;

$response = TextResponse::fromText( '...' );
$response->add( '...' ); // add more texts

TextResponse objects also support fromAsync() for asynchronous APIs using a closure function and the optional timeout between requests as second parameter:

$client = $this->client();
$response = TextResponse::fromAsync( function( FileResponse $fr ) uses ( $client ) {
    // download and add texts to text response object
    $fr->add( '...' );
}, 3 );

Vector response

The vectorize() method returns a VectorResponse object which contains the vector of float numbers representing the input:

use Aimeos\Prisma\Responses\VectorResponse;

$response = VectorResponse::fromVectors( [
    [0.27629, 0.89271, 0.98265, /* ... */],
    /* ... */
] );

Meta data

All response objects support adding usage information and meta data if they are returned by the provider API. Use the withUsage() and *withMeta() methods to pass that information as part of the response object:

$response->withUsage( // optional
    100, // used tokens, credits, etc. if available or NULL
    [] // arbitrary key/value pairs for the rest of the usage information
);
$response->withMeta( // optional
    [] // arbitrary meta data as key/value pairs, can be nested
);

TextResponse objects can store structured data e.g. returned when audio files are transcribed:

$response->withStructured( [
    // for transcriptions
    ['start' => 0.0, 'end' => 1.0, 'text' => 'This is a test.'],
    // ...
] );

Transcriptions must always contain the keys start and end in seconds as well as text for the content in each entry (but there can be more key/value pairs if available).

The FileResponse object also supports withDescription() to attach the file description as string to the response object:

$response->withDescription( '...' );

Examples

Audio provider

<?php

namespace Aimeos\Prisma\Providers\Audio;

use Aimeos\Prisma\Contracts\Audio\Describe;
use Aimeos\Prisma\Exceptions\PrismaException;
use Aimeos\Prisma\Files\Audio;
use Aimeos\Prisma\Providers\Base;
use Aimeos\Prisma\Responses\TextResponse;


class Myprovider extends Base implements Describe
{
    public function __construct( array $config )
    {
        if( !isset( $config['api_key'] ) ) {
            throw new PrismaException( sprintf( 'No API key' ) );
        }

        $this->header( 'x-api-key', $config['api_key'] );
        $this->baseUrl( 'https://ai.com' );
    }


    public function describe( Audio $audio, ?string $lang = null, array $options = [] ) : TextResponse
    {
        $allowed = $this->allow( $options, ['version'] );
        $model = $this->modelName( 'flash' );

        $params = ['language' => $lang, 'model' => model] + $allowed;
        $data = ['multipart' => $this->request( params, ['file' = $audio->binary()] )];
        $response = $this->client()->post( 'relative/api/path', $data );

        $this->validate( $response );

        $data = $this->fromJson( $response );

        return TextResponse::fromText( @$data['text'] )
            ->withStructured( // optional
                $data['segments'] ?? []
            )
            ->withUsage( // optional
                @$data['usage']['total'],
                $data['usage'] ?? []
            )
            ->withMeta( // optional
                $data['meta'] ?? []
            );
    }
}

Image provider

<?php

namespace Aimeos\Prisma\Providers\Image;

use Aimeos\Prisma\Contracts\Image\Describe;
use Aimeos\Prisma\Exceptions\PrismaException;
use Aimeos\Prisma\Files\Image;
use Aimeos\Prisma\Providers\Base;
use Aimeos\Prisma\Responses\TextResponse;


class Myprovider extends Base implements Describe
{
    public function __construct( array $config )
    {
        if( !isset( $config['api_key'] ) ) {
            throw new PrismaException( sprintf( 'No API key' ) );
        }

        $this->header( 'x-api-key', $config['api_key'] );
        $this->baseUrl( 'https://ai.com' );
    }


    public function describe( Image $audio, ?string $lang = null, array $options = [] ) : TextResponse
    {
        $allowed = $this->allow( $options, ['version'] );
        $model = $this->modelName( 'flash' );

        $params = ['language' => $lang, 'model' => model] + $allowed;
        $data = ['multipart' => $this->request( params, ['file' = $audio->binary()] )];
        $response = $this->client()->post( 'relative/api/path', $data );

        $this->validate( $response );

        $data = $this->fromJson( $response );

        return TextResponse::fromText( @$data['text'] )
            ->withStructured( // optional
                $data['segments'] ?? []
            )
            ->withUsage( // optional
                @$data['usage']['total'],
                $data['usage'] ?? []
            )
            ->withMeta( // optional
                $data['meta'] ?? []
            );
    }
}

Video provider

<?php

namespace Aimeos\Prisma\Providers\Video;

use Aimeos\Prisma\Contracts\Video\Describe;
use Aimeos\Prisma\Exceptions\PrismaException;
use Aimeos\Prisma\Files\Video;
use Aimeos\Prisma\Providers\Base;
use Aimeos\Prisma\Responses\TextResponse;


class Myprovider extends Base implements Describe
{
    public function __construct( array $config )
    {
        if( !isset( $config['api_key'] ) ) {
            throw new PrismaException( sprintf( 'No API key' ) );
        }

        $this->header( 'x-api-key', $config['api_key'] );
        $this->baseUrl( 'https://ai.com' );
    }


    public function describe( Video $video, ?string $lang = null, array $options = [] ) : TextResponse
    {
        $allowed = $this->allow( $options, ['version'] );
        $model = $this->modelName( 'flash' );

        $params = ['language' => $lang, 'model' => model] + $allowed;
        $data = ['multipart' => $this->request( params, ['file' = $video->binary()] )];
        $response = $this->client()->post( 'relative/api/path', $data );

        $this->validate( $response );

        $data = $this->fromJson( $response );

        return TextResponse::fromText( @$data['text'] )
            ->withStructured( // optional
                $data['segments'] ?? []
            )
            ->withUsage( // optional
                @$data['usage']['total'],
                $data['usage'] ?? []
            )
            ->withMeta( // optional
                $data['meta'] ?? []
            );
    }
}