Skip to main content

​
Overview

Prism provides a simple API for generating images using AI models from supported providers like OpenAI’s DALL-E. The Prism::image() method allows you to create images from text descriptions.
Check the provider documentation to see which providers support image generation and what models are available.

​
Basic Usage

Generate an image from a text prompt: 
use Prism\Prism\Facades\Prism;

$response = Prism::image()
    ->using('openai', 'dall-e-3')
    ->withPrompt('A serene mountain landscape at sunset')
    ->generate();

$image = $response->firstImage();

​
Configuring the Request

​
Selecting Provider and Model

Specify which provider and model to use for image generation: 
use Prism\Prism\Enums\Provider;

$response = Prism::image()
    ->using(Provider::OpenAI, 'dall-e-3')
    ->withPrompt('A futuristic city with flying cars')
    ->generate();

​
Adding System Prompts

Provide system-level instructions to guide image generation: 
$response = Prism::image()
    ->using('openai', 'dall-e-3')
    ->withSystemPrompt('Generate images in a watercolor painting style')
    ->withPrompt('A forest scene with wildlife')
    ->generate();

​
Including Reference Images

Some providers support using reference images for image editing or variation: 
use Prism\Prism\ValueObjects\Media\Image;

$response = Prism::image()
    ->using('openai', 'dall-e-2')
    ->withPrompt('Add a sunset to this landscape', [
        Image::fromLocalPath('/path/to/original.png')
    ])
    ->generate();
Reference images are filtered automatically - only Image media types are included in the request.

​
Provider-Specific Options

Configure provider-specific settings using withProviderOptions(): 
$response = Prism::image()
    ->using('openai', 'dall-e-3')
    ->withPrompt('A minimalist logo design')
    ->withProviderOptions([
        'size' => '1024x1024',
        'quality' => 'hd',
        'style' => 'vivid'
    ])
    ->generate();
Provider options vary by provider and model. Consult your provider’s documentation for available options.

​
Working with Responses

​
Accessing Generated Images

The response contains an array of generated images: 
$response = Prism::image()
    ->using('openai', 'dall-e-3')
    ->withPrompt('Abstract geometric patterns')
    ->generate();

// Get the first image
$image = $response->firstImage();

// Access all images
foreach ($response->images as $image) {
    echo $image->url ?? 'No URL';
}

// Check if images were generated
if ($response->hasImages()) {
    echo "Generated {$response->imageCount()} images";
}

​
Image Properties

Each GeneratedImage object contains: 
// Image URL (if provided by the provider)
$url = $image->url;

​
Saving Images

Save generated images to disk: 
$response = Prism::image()
    ->using('openai', 'dall-e-3')
    ->withPrompt('A beautiful ocean view')
    ->generate();

$image = $response->firstImage();

if ($image->url) {
    // Download from URL
    $content = file_get_contents($image->url);
    file_put_contents('/path/to/save/image.png', $content);
} elseif ($image->base64) {
    // Decode base64
    $content = base64_decode($image->base64);
    file_put_contents('/path/to/save/image.png', $content);
}

​
Usage and Metadata

​
Usage Information

Track API usage for your image generation requests: 
$response = Prism::image()
    ->using('openai', 'dall-e-3')
    ->withPrompt('Digital art of a robot')
    ->generate();

echo "Images generated: {$response->usage->imagesGenerated}";

​
Response Metadata

Access provider metadata and raw response data: 
// Provider information
echo "Provider: {$response->meta->provider}";
echo "Model: {$response->meta->model}";

// Raw response from provider
$rawData = $response->raw;

// Additional content from provider
$additionalContent = $response->additionalContent;

​
Converting to Array

Convert the response to an array for serialization: 
$response = Prism::image()
    ->using('openai', 'dall-e-3')
    ->withPrompt('Futuristic architecture')
    ->generate();

$array = $response->toArray();
// Returns:
// [
//   'images' => [...],
//   'usage' => [...],
//   'meta' => [...],
//   'additional_content' => [...],
//   'raw' => [...]
// ]

​
Client Configuration

​
HTTP Options

Configure HTTP client behavior: 
$response = Prism::image()
    ->using('openai', 'dall-e-3')
    ->withPrompt('A peaceful garden')
    ->withClientOptions([
        'timeout' => 120,
        'connect_timeout' => 30
    ])
    ->generate();

​
Retry Configuration

Configure automatic retries for failed requests: 
$response = Prism::image()
    ->using('openai', 'dall-e-3')
    ->withPrompt('Abstract art')
    ->withClientRetry(
        times: 3,
        sleepMilliseconds: 1000
    )
    ->generate();

​
Error Handling

Handle errors gracefully when generating images: 
use Illuminate\Http\Client\RequestException;

try {
    $response = Prism::image()
        ->using('openai', 'dall-e-3')
        ->withPrompt('A fantasy landscape')
        ->generate();
    
    $image = $response->firstImage();
} catch (RequestException $e) {
    // Handle API errors
    echo "Error: {$e->getMessage()}";
}

​
Best Practices

Use detailed, descriptive prompts for better results:
// Good
$response = Prism::image()
    ->withPrompt('A photorealistic portrait of a wise elderly man with a white beard, wearing a blue robe, standing in a medieval library filled with ancient books, warm lighting from candles')
    ->generate();

// Less effective
$response = Prism::image()
    ->withPrompt('Old man in library')
    ->generate();

​
Next Steps

Audio Processing

Convert text to speech or transcribe audio files

Embeddings

Generate vector embeddings for text and images

Content Moderation

Check content for safety and compliance

Providers

Learn about provider-specific features

Build docs developers (and LLMs) love

Get started for freeTalk to us