Download the PHP package tigusigalpa/monica-api-php without Composer

Monica AI API PHP Client/SDK

A powerful and elegant PHP client (SDK) library for Monica API Platform - your unified gateway to multiple AI models from leading providers.

🚀 Features

• Unified API Access: Single interface to multiple AI providers (OpenAI, Anthropic, Google, DeepSeek, Meta, Grok, NVIDIA, Mistral)
• Latest AI Models: Support for cutting-edge models including GPT-5, Claude 4, and Gemini 2.5
• Image Generation: Support for FLUX, Stable Diffusion, DALL·E, Playground, and Ideogram models
• Type Safety: Full PHP 8.1+ type declarations and strict typing
• Rich Documentation: Comprehensive PHPDoc comments and examples
• Error Handling: Robust exception handling with detailed error information
• Flexible Configuration: Support for all major AI model parameters
• Laravel Ready: Perfect integration with Laravel applications
• PSR-4 Autoloading: Modern PHP standards compliance

📋 Supported AI Models

📝 Note: Only OpenAI, Anthropic (Claude), and Google (Gemini) models support image input in chat requests. Other providers will return an error if images are included in the request.

🎨 Supported Image Generation Models

FLUX Models

• FLUX.1 Schnell: Entry-level model optimized for speed and efficiency
• FLUX.1 Dev: Developer-focused variant with enhanced customization options
• FLUX.1 Pro: Professional-grade model with highest quality output

Stable Diffusion Models

• Stable Diffusion XL 1.0: Efficient image generation with good quality
• Stable Diffusion 3: Advanced model with better prompting and higher quality
• Stable Diffusion 3.5 Large: Latest model with exceptional detail and realism

DALL·E Models

• DALL·E 3: Highly detailed and photorealistic images with superior understanding

Playground Models

• Playground V2.5: Cost-effective solution with strong artistic style interpretation

Ideogram Models

• Ideogram V2: Exceptional text rendering capabilities, ideal for logos and typography

🛠 Installation

Install via Composer:

🔧 Requirements

• PHP 8.1 or higher
• Guzzle HTTP 7.0+
• Monica AI API key (Get yours here)

🚀 Quick Start

📖 Usage Examples

Basic Chat Completion

Advanced Configuration

Conversation with Multiple Messages

Understanding Chat Methods: chat() vs chatWithMessages()

MonicaAPI provides two main methods for chat interactions, each designed for different use cases:

Method Comparison

When to Use chat()

Perfect for simple, standalone interactions:

When to Use chatWithMessages()

Essential for complex message structures:

Migration Guide

If you need to upgrade from chat() to chatWithMessages():

Chat with Images (Vision Models)

Vision-capable models like GPT-5 and GPT-4o can analyze and discuss images. Here are examples of how to upload images to chat:

Upload Image from File

Upload Image from URL

Upload Multiple Images

Upload Image from Base64

Advanced Image Chat Example

Working with Image Details

Supported Vision Models

The following models support image analysis:

• GPT-5: Most advanced image analysis and understanding capabilities
• GPT-4o: Excellent for detailed image analysis and understanding
• GPT-4o Mini: Faster, cost-effective option for basic image tasks

Creating Messages from Array Data

You can create ChatMessage instances directly from array data using the fromArray() method. This is particularly useful when working with pre-structured message data or when integrating with existing systems that use OpenAI-compatible message formats.

Basic Usage

Multimodal Messages with Mixed Content

Working with Conversation Arrays

Helper Function for Batch Processing

Supported Array Structure

The fromArray() method supports the following message structure:

🎨 Image Generation Usage

Simple Image Generation

Advanced Image Generation

Model-Specific Examples

DALL·E 3 with Quality Options

Ideogram V2 for Text and Logos

Playground V2.5 with Multiple Outputs

Model Management

Error Handling

Working with Response Data

🔧 Configuration Options

Chat Completion Parameters

Example with All Parameters

🏗 Laravel Integration

Service Provider Registration

Service Provider Example

Configuration

Environment Variables

Controller Example

🧪 Testing

Run the test suite:

Run with coverage:

📚 API Reference

MonicaClient

Constructor

Methods

• chat(string $message, array $options = []): ChatCompletionResponse
• chatWithMessages(ChatMessage[] $messages, array $options = []): ChatCompletionResponse
• generateImage(ImageGeneration $imageGeneration): ImageGenerationResponse
• generateImageSimple(string $model, string $prompt, array $options = []): ImageGenerationResponse
• setModel(string $model): void
• getModel(): string
• isModelSupported(string $model): bool
• static getSupportedModels(): array
• static getModelsByProvider(string $provider): array
• static getAllModelIds(): array
• static getSupportedImageModels(): array

ChatMessage

Static Constructors

• ChatMessage::system(string $content, ?string $name = null): ChatMessage
• ChatMessage::user(string $content, ?string $name = null): ChatMessage
• ChatMessage::assistant(string $content, ?string $name = null): ChatMessage
• ChatMessage::userWithImage(string $content, string $imageUrl): ChatMessage
• ChatMessage::userWithImages(string $content, array $imageUrls): ChatMessage
• ChatMessage::fromArray(array $data): ChatMessage

Methods

• getRole(): string
• getContent(): string
• getName(): ?string
• isSystem(): bool
• isUser(): bool
• isAssistant(): bool
• hasImages(): bool
• getImages(): array
• addImageFromFile(string $filePath, string $detail = 'auto'): self
• addImageFromUrl(string $url, string $detail = 'auto'): self
• addImageFromBase64(string $base64Data, string $mimeType, string $detail = 'auto'): self
• toArray(): array

ChatCompletionResponse

Methods

• getContent(): string
• getRole(): string
• getFinishReason(): ?string
• getTotalTokens(): int
• getPromptTokens(): int
• getCompletionTokens(): int
• isComplete(): bool
• wasTruncated(): bool
• wasFiltered(): bool
• getFirstChoice(): ?array
• getFirstChoiceAsMessage(): ?ChatMessage
• getAllChoices(): array

ImageGeneration

Constructor

Methods

• getModel(): string
• getPrompt(): string
• setNegativePrompt(string $negativePrompt): self
• setNumOutputs(int $numOutputs): self
• setSize(string $size): self
• setSeed(int $seed): self
• setSteps(int $steps): self
• setGuidance(float $guidance): self
• setCfgScale(float $cfgScale): self
• setQuality(string $quality): self
• setStyle(string $style): self
• setAspectRatio(string $aspectRatio): self
• setMagicPromptOption(string $option): self
• setStyleType(string $styleType): self
• setSafetyTolerance(int $tolerance): self
• static isModelSupported(string $model): bool
• static getSupportedModels(): array
• toArray(): array

ImageGenerationResponse

Methods

• getImageUrls(): array
• getFirstImageUrl(): ?string
• saveFirstImage(string $filePath): bool
• saveAllImages(string $directory, string $prefix = 'image_', string $extension = 'png'): array
• getImageCount(): int

📝 Changelog

[Unreleased]

Added

• GPT-5 Support: Added support for OpenAI's latest flagship model gpt-5
  • Full chat completion capabilities with advanced reasoning
  • Enhanced image analysis and multimodal understanding
  • Updated default model examples to showcase GPT-5
  • Added GPT-5 to supported vision models list

Changed

• Updated Quick Start example to use GPT-5 as the default model
• Enhanced Laravel integration examples with GPT-5 configuration
• Updated model comparison tables to highlight GPT-5 capabilities

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Clone the repository
2. Install dependencies: composer install
3. Run tests: composer test
4. Check code style: composer cs-check
5. Fix code style: composer cs-fix

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Monica API Platform
• API Documentation
• GitHub Repository
• Packagist

💬 Support

If you have any questions or need help, please:

1. Check the documentation
2. Search existing GitHub issues
3. Create a new issue if needed

🙏 Acknowledgments

• Monica API Platform for providing the unified AI API
• All the AI providers (OpenAI, Anthropic, Google, etc.) for their amazing models
• The PHP community for excellent tools and libraries