aimeos/prisma

A powerful PHP package for integrating media related Large Language Models (LLMs) into your applications

0.3.0 2026-02-16 08:17 UTC

Requires

• php: ^8.1
• ext-fileinfo: *
• ext-gd: *
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• firebase/php-jwt: ^6.11
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^10.5||^11.5||^12.4
• vlucas/phpdotenv: ^5.6

LGPL-2.1+

README

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

Supported providers

• Audio
• Image
• Video

API usage

• ensure: Ensures that the provider has implemented the method
• has: Tests if the provider has implemented the method
• model: Use the model passed by its name
• withClientOptions: Add options for the Guzzle HTTP client
• withSystemPrompt: Add a system prompt for the LLM
• Response objects: How data is returned by the API

Audio API

• demix: Separate an audio file into its individual tracks
• denoise: Remove noise from an audio file
• describe: Describe the content of an audio file
• revoice: Exchange the voice in an audio file
• speak: Convert text to speech in an audio file
• transcribe: Converts speech of an audio file to text

Image API

• background: Replace background according to the prompt
• describe: Describe the content of an image
• detext: Remove all text from the image
• erase: Erase parts of the image
• imagine: Generate an image from the prompt
• inpaint: Edit an image area according to a prompt
• isolate: Remove the image background
• relocate: Place the foreground object on a new background
• repaint: Repaint an image according to the prompt
• uncrop: Extend/outpaint the image
• upscale: Scale up the image
• vectorize: Creates embedding vectors from images

Video API

• describe: Describe the content of a video

Custom providers

• Base skeleton
• Requests
• Responses
• Examples

Supported providers

• AudioPod AI
• Bedrock Titan (AWS)
• Black Forest Labs
• Clipdrop
• Cohere
• Deepgram
• ElevenLabs
• Gemini (Google)
• Groq
• Ideogram
• Mistral
• Murf
• OpenAI
• RemoveBG
• StabilityAI
• VertexAI (Google)
• VoyageAI

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

• @param string $method Method name
• @return Provider
• @throws \Aimeos\Prisma\Exceptions\NotImplementedException

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

• @param string $method Method name
• @return bool TRUE if implemented, FALSE if absent

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

• @param string|null $model Model name
• @return self Provider interface

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

• @param array<string, mixed> $options Associative list of name/value pairs
• @return self Provider interface

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

• @param string|null $prompt System prompt
• @return self Provider interface

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

• @param Audio $audio Input audio object
• @param int $stems Number of stems to separate into (e.g. 2 for vocals and accompaniment)
• @param array<string, mixed> $options Provider specific options
• @return FileResponse Audio file response

Supported options:

• AudioPod

denoise

Remove noise from an audio file.

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

• @param Audio $audio Input audio object
• @param array<string, mixed> $options Provider specific options
• @return FileResponse Audio file response

Supported options:

• AudioPod

describe

Describe the content of an audio file.

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

• @param Audio $audio Input audio object
• @param string|null $lang ISO language code the description should be generated in
• @param array<string, mixed> $options Provider specific options
• @return TextResponse Response text

Supported options:

• Gemini
• Groq
• OpenAI

revoice

Exchange the voice in an audio file.

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

• @param Audio $audio Input audio object
• @param string $voice Voice name or identifier
• @param array<string, mixed> $options Provider specific options
• @return FileResponse Audio file response

Supported options:

• AudioPod
• ElevenLabs
• Murf

speak

Converts text to speech.

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

• @param string $text Text to be converted to speech
• @param string|null $voice Voice identifier for speech synthesis
• @param array<string, mixed> $options Provider specific options
• @return FileResponse Audio file response

Supported options:

• AudioPod
• Deepgram
• ElevenLabs
• Groq
• Murf
• OpenAI

transcribe

Converts speech to text.

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

• @param Audio $audio Input audio object
• @param string|null $lang ISO language code of the audio content
• @param array<string, mixed> $options Provider specific options
• @return TextResponse Transcription text response

Supported options:

• AudioPod
• Deepgram
• ElevenLabs
• Groq
• Mistral
• OpenAI

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

• @param Image $image Input image object
• @param string $prompt Prompt describing the new background
• @param array<string, mixed> $options Provider specific options
• @return FileResponse Response file

Supported options:

• Clipdrop
• Ideogram
• VertexAI

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

• @param Image $image Input image object
• @param string|null $lang ISO language code the description should be generated in
• @param array<string, mixed> $options Provider specific options
• @return TextResponse Response text

Supported options:

• Gemini
• Groq
• Ideogram
• OpenAI

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

• @param Image $image Input image object
• @param array<string, mixed> $options Provider specific options
• @return FileResponse Response file

Supported options:

• Clipdrop

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

• @param Image $image Input image object
• @param Image $mask Mask image object
• @param array<string, mixed> $options Provider specific options
• @return FileResponse Response file

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

Supported options:

• Clipdrop
• StabilityAI

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

• @param string $prompt Prompt describing the image
• @param array<int, \Aimeos\Prisma\Files\Image> $images Associative list of file name/Image instances
• @param array<string, mixed> $options Provider specific options
• @return FileResponse Response file

Supported options:

• Bedrock
• Black Forest Labs
• Clipdrop
• Gemini
• Ideogram
• VertexAI
• OpenAI GPT image 1
• OpenAI Dall-e-3
• OpenAI Dall-e-2
• StabilityAI Core
• StabilityAI Ultra
• StabilityAI Stable Diffusion 3.5

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

• @param Image $image Input image object
• @param Image $mask Input mask image object
• @param string $prompt Prompt describing the changes
• @param array<string, mixed> $options Provider specific options
• @return FileResponse Response file

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

Supported options:

• Bedrock
• Black Forest Labs
• Ideogram
• VertexAI
• OpenAI GPT image 1
• OpenAI Dall-e-3
• OpenAI Dall-e-2
• StabilityAI

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

• @param Image $image Input image object
• @param array<string, mixed> $options Provider specific options
• @return FileResponse Response file

Supported options:

• Bedrock
• Clipdrop
• RemoveBG
• StabilityAI

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;

• @param Image $image Input image object
• @param array<string, mixed> $options Provider specific options
• @return TextResponse Response text object

Supported options:

• Mistral

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

• @param Image $image Input image with foreground object
• @param Image $bgimage Background image
• @param array<string, mixed> $options Provider specific options
• @return FileResponse Response file

Supported options:

• RemoveBG

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

• @param Image $image Input image object
• @param string $prompt Prompt describing the changes
• @param array<string, mixed> $options Provider specific options
• @return FileResponse Response file

Supported options:

• Gemini
• Ideogram

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

• @param Image $image Input image object
• @param int $top Number of pixels to extend to the top
• @param int $right Number of pixels to extend to the right
• @param int $bottom Number of pixels to extend to the bottom
• @param int $left Number of pixels to extend to the left
• @param array<string, mixed> $options Provider specific options
• @return FileResponse Response file

Supported options:

• Black Forest Labs
• Clipdrop
• StabilityAI

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

• @param Image $image Input image object
• @param int $factor Upscaling factor between 2 and the maximum value supported by the provider
• @param array<string, mixed> $options Provider specific options
• @return FileResponse Response file

Supported options:

• Clipdrop
• Ideogram
• VertexAI
• StabilityAI

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

• @param array<int, \Aimeos\Prisma\Files\Image> $images List of input image objects
• @param int|null $size Size of the resulting vector or null for provider default
• @param array<string, mixed> $options Provider specific options
• @return VectorResponse Response vector object

Supported options:

• Bedrock
• Cohere
• VertexAI
• VoyageAI

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

• @param Video $video Input video object
• @param string|null $lang ISO language code the description should be generated in
• @param array<string, mixed> $options Provider specific options
• @return TextResponse Response text

Supported options:

• Gemini

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:

• Audio
• Image
• Video

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:

• FileResponse
• TextResponse
• VectorResponse

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'] ?? []
            );
    }
}