{"id":36339502,"url":"https://github.com/tigusigalpa/monica-ai-php","last_synced_at":"2026-01-14T00:37:13.045Z","repository":{"id":311256107,"uuid":"1043151975","full_name":"tigusigalpa/monica-ai-php","owner":"tigusigalpa","description":"A powerful PHP client library for Monica AI API Platform - your unified gateway to multiple AI models (OpenAI, Anthropic, Google, DeepSeek, Meta, Grok, NVIDIA, Mistral). Features type safety, Laravel support, image generation capabilities, and comprehensive documentation. Perfect for AI integration in PHP projects.","archived":false,"fork":false,"pushed_at":"2025-11-21T08:44:25.000Z","size":94,"stargazers_count":15,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T15:49:17.715Z","etag":null,"topics":["ai","api","claude-ai","gemini","gpt","gpt-5","gpt-5-api","grok-api","monica-ai","php","php8","sdk"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tigusigalpa.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-23T08:47:31.000Z","updated_at":"2025-12-31T18:57:13.000Z","dependencies_parsed_at":"2025-08-23T11:01:26.489Z","dependency_job_id":"aaf693d3-bb71-4aec-ac7d-6e07405783e2","html_url":"https://github.com/tigusigalpa/monica-ai-php","commit_stats":null,"previous_names":["tigusigalpa/monica-api-php","tigusigalpa/monica-ai-php"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/tigusigalpa/monica-ai-php","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigusigalpa%2Fmonica-ai-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigusigalpa%2Fmonica-ai-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigusigalpa%2Fmonica-ai-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigusigalpa%2Fmonica-ai-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tigusigalpa","download_url":"https://codeload.github.com/tigusigalpa/monica-ai-php/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigusigalpa%2Fmonica-ai-php/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28406520,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T21:51:37.118Z","status":"ssl_error","status_checked_at":"2026-01-13T21:45:14.585Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","api","claude-ai","gemini","gpt","gpt-5","gpt-5-api","grok-api","monica-ai","php","php8","sdk"],"created_at":"2026-01-11T12:54:55.755Z","updated_at":"2026-01-14T00:37:13.019Z","avatar_url":"https://github.com/tigusigalpa.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Monica AI API PHP Client/SDK\n\n[![PHP Version](https://img.shields.io/badge/php-%5E8.1-blue.svg)](https://www.php.net/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Latest Version](https://img.shields.io/github/v/release/tigusigalpa/monica-ai-php)](https://github.com/tigusigalpa/monica-api-php/releases)\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/0ca1fc1f-0e64-415f-9fd1-ecdca727499a\" alt=\"Monica AI PHP SDK\" style=\"max-width: 100%; height: auto;\"\u003e\n\u003c/div\u003e\n\nA powerful and elegant PHP client (SDK) library for [Monica API Platform](https://platform.monica.im/) - your unified\ngateway\nto multiple AI models from leading providers.\n\n## 🚀 Features\n\n- **Unified API Access**: Single interface to multiple AI providers (OpenAI, Anthropic, Google, DeepSeek, Meta, Grok,\n  NVIDIA, Mistral)\n- **Latest AI Models**: Support for cutting-edge models including GPT-5, Claude 4, and Gemini 2.5\n- **Image Generation**: Support for FLUX, Stable Diffusion, DALL·E, Playground, and Ideogram models\n- **Type Safety**: Full PHP 8.1+ type declarations and strict typing\n- **Rich Documentation**: Comprehensive PHPDoc comments and examples\n- **Error Handling**: Robust exception handling with detailed error information\n- **Flexible Configuration**: Support for all major AI model parameters\n- **Laravel Ready**: Perfect integration with Laravel applications\n- **PSR-4 Autoloading**: Modern PHP standards compliance\n\n## 📋 Supported AI Models\n\n| Provider      | Model                                    | Description                    | Image Input Support |\n|---------------|------------------------------------------|--------------------------------|---------------------|\n| **OpenAI**    | `gpt-5`                                  | GPT-5 (Latest flagship model)  | ✅ Yes               |\n|               | `gpt-4.1`                                | GPT-4.1 (Main model)           | ✅ Yes               |\n|               | `gpt-4.1-mini`                           | GPT-4.1 Mini (Lightweight)     | ✅ Yes               |\n|               | `gpt-4.1-nano`                           | GPT-4.1 Nano (Ultra-light)     | ✅ Yes               |\n|               | `gpt-4o`                                 | GPT-4o (With image support)    | ✅ Yes               |\n|               | `gpt-4o-mini`                            | GPT-4o Mini (Lightweight)      | ✅ Yes               |\n| **Anthropic** | `claude-sonnet-4-20250514`               | Claude 4 Sonnet                | ✅ Yes               |\n|               | `claude-opus-4-20250514`                 | Claude 4 Opus                  | ✅ Yes               |\n|               | `claude-3-7-sonnet-latest`               | Claude 3.7 Sonnet              | ✅ Yes               |\n|               | `claude-3-5-sonnet-latest`               | Claude 3.5 Sonnet              | ✅ Yes               |\n|               | `claude-3-5-haiku-latest`                | Claude 3.5 Haiku               | ❌ No                |\n| **Google**    | `gemini-2.5-pro`                         | Gemini 2.5 Pro Preview         | ✅ Yes               |\n|               | `gemini-2.5-flash`                       | Gemini 2.5 Flash               | ✅ Yes               |\n| **DeepSeek**  | `deepseek-reasoner`                      | DeepSeek V3 Reasoner           | ❌ No                |\n|               | `deepseek-chat`                          | DeepSeek V3 Chat               | ❌ No                |\n| **Meta**      | `meta-llama/llama-3-8b-instruct`         | Meta: Llama 3 8B Instruct      | ❌ No                |\n|               | `meta-llama/llama-3.1-8b-instruct`       | Meta: Llama 3.1 8B Instruct    | ❌ No                |\n| **Grok**      | `x-ai/grok-3-beta`                       | Grok 3 Beta                    | ❌ No                |\n| **NVIDIA**    | `nvidia/llama-3.1-nemotron-70b-instruct` | NVIDIA: Llama 3.1 Nemotron 70B | ❌ No                |\n| **Mistral**   | `mistralai/mistral-7b-instruct`          | Mistral: Mistral 7B Instruct   | ❌ No                |\n\n\u003e **📝 Note**: Only OpenAI, Anthropic (Claude), and Google (Gemini) models support image input in chat requests. Other\n\u003e providers will return an error if images are included in the request.\n\n## 🎨 Supported Image Generation Models\n\n### FLUX Models\n\n- **FLUX.1 Schnell**: Entry-level model optimized for speed and efficiency\n- **FLUX.1 Dev**: Developer-focused variant with enhanced customization options\n- **FLUX.1 Pro**: Professional-grade model with highest quality output\n\n### Stable Diffusion Models\n\n- **Stable Diffusion XL 1.0**: Efficient image generation with good quality\n- **Stable Diffusion 3**: Advanced model with better prompting and higher quality\n- **Stable Diffusion 3.5 Large**: Latest model with exceptional detail and realism\n\n### DALL·E Models\n\n- **DALL·E 3**: Highly detailed and photorealistic images with superior understanding\n\n### Playground Models\n\n- **Playground V2.5**: Cost-effective solution with strong artistic style interpretation\n\n### Ideogram Models\n\n- **Ideogram V2**: Exceptional text rendering capabilities, ideal for logos and typography\n\n## 🛠 Installation\n\nInstall via Composer:\n\n```bash\ncomposer require tigusigalpa/monica-ai-php\n```\n\n## 🔧 Requirements\n\n- PHP 8.1 or higher\n- Guzzle HTTP 7.0+\n- Monica AI API key ([Get yours here](https://platform.monica.im/))\n\n## 🚀 Quick Start\n\n```php\n\u003c?php\n\nrequire_once 'vendor/autoload.php';\n\nuse Tigusigalpa\\MonicaAI\\MonicaClient;\nuse Tigusigalpa\\MonicaAI\\Exceptions\\MonicaAIException;\nuse Tigusigalpa\\MonicaAI\\Exceptions\\InvalidModelException;\n\n// Initialize the client with GPT-5 (latest flagship model)\n$client = new MonicaClient('your-monica-api-key', 'gpt-5');\n\ntry {\n    // Simple chat completion\n    $response = $client-\u003echat('Hello! How are you today?');\n    echo $response-\u003egetContent();\n    \n} catch (MonicaAIException $e) {\n    echo \"API Error: \" . $e-\u003egetMessage();\n} catch (InvalidModelException $e) {\n    echo \"Invalid Model: \" . $e-\u003egetMessage();\n}\n```\n\n## 📖 Usage Examples\n\n### Basic Chat Completion\n\n```php\nuse Tigusigalpa\\MonicaAI\\MonicaClient;\n\n// Use GPT-5 for the most advanced AI capabilities\n$client = new MonicaClient('your-api-key', 'gpt-5');\n\n$response = $client-\u003echat('Explain quantum computing in simple terms');\necho $response-\u003egetContent();\n```\n\n### Advanced Configuration\n\n```php\n$response = $client-\u003echat('Write a creative story', [\n    'system' =\u003e 'You are a creative storyteller',\n    'temperature' =\u003e 0.8,\n    'max_tokens' =\u003e 500,\n    'top_p' =\u003e 0.9\n]);\n```\n\n### Conversation with Multiple Messages\n\n```php\nuse Tigusigalpa\\MonicaAI\\Models\\ChatMessage;\n\n$messages = [\n    ChatMessage::system('You are a helpful programming assistant'),\n    ChatMessage::user('How do I create a PHP class?'),\n    ChatMessage::assistant('To create a PHP class, use the `class` keyword...'),\n    ChatMessage::user('Can you show me an example?')\n];\n\n$response = $client-\u003echatWithMessages($messages, [\n    'temperature' =\u003e 0.3,\n    'max_tokens' =\u003e 1000\n]);\n```\n\n### Understanding Chat Methods: `chat()` vs `chatWithMessages()`\n\nMonicaAI provides two main methods for chat interactions, each designed for different use cases:\n\n#### Method Comparison\n\n| Feature               | `chat()`                    | `chatWithMessages()`                   |\n|-----------------------|-----------------------------|----------------------------------------|\n| **Input Type**        | `string` (simple text)      | `ChatMessage[]` (array of messages)    |\n| **Use Case**          | Single message              | Multiple messages in one request       |\n| **Message Structure** | ✅ Auto-creates user message | ✅ Full control over message roles      |\n| **Image Support**     | ❌ Text only                 | ✅ Multimodal (text + images)           |\n| **System Messages**   | ✅ Via options parameter     | ✅ As separate ChatMessage objects      |\n| **Complexity**        | 🟢 Simple and quick         | 🟡 More setup required                 |\n| **Flexibility**       | 🟡 Limited customization    | 🟢 Full control over message structure |\n| **Best For**          | Quick queries, testing      | Complex messages, image analysis       |\n\n#### When to Use `chat()`\n\nPerfect for simple, standalone interactions:\n\n```php\n// Quick questions\n$response = $client-\u003echat('What is the capital of France?');\n\n// Simple tasks with system context\n$response = $client-\u003echat('Translate this to Spanish: Hello world', [\n    'system' =\u003e 'You are a professional translator',\n    'temperature' =\u003e 0.3\n]);\n\n// Testing and prototyping\n$response = $client-\u003echat('Explain quantum physics in simple terms');\n```\n\n#### When to Use `chatWithMessages()`\n\nEssential for complex message structures:\n\n```php\n// Multiple messages with different roles\n$messages = [\n    ChatMessage::system('You are a helpful coding assistant'),\n    ChatMessage::user('How do I create a REST API in PHP?'),\n    ChatMessage::assistant('To create a REST API in PHP, you can use...'),\n    ChatMessage::user('Can you show me a complete example?')\n];\n\n$response = $client-\u003echatWithMessages($messages);\n\n// Image analysis (requires chatWithMessages)\n$message = ChatMessage::user('What do you see in this image?');\n$message-\u003eaddImageFromFile('photo.jpg');\n\n$response = $client-\u003echatWithMessages([$message]);\n\n// Complex multimodal messages\n$messageData = [\n    'role' =\u003e 'user',\n    'content' =\u003e [\n        ['type' =\u003e 'text', 'text' =\u003e 'Analyze this diagram:'],\n        ['type' =\u003e 'image_url', 'image_url' =\u003e ['url' =\u003e 'data:image/jpeg;base64,...']]\n    ]\n];\n\n$message = ChatMessage::fromArray($messageData);\n$response = $client-\u003echatWithMessages([$message]);\n```\n\n#### Migration Guide\n\nIf you need to upgrade from `chat()` to `chatWithMessages()`:\n\n```php\n// Before: Using chat()\n$response = $client-\u003echat('Hello, how are you?', [\n    'system' =\u003e 'You are a friendly assistant'\n]);\n\n// After: Using chatWithMessages()\n$messages = [\n    ChatMessage::system('You are a friendly assistant'),\n    ChatMessage::user('Hello, how are you?')\n];\n\n$response = $client-\u003echatWithMessages($messages);\n```\n\n### Chat with Images (Vision Models)\n\nVision-capable models like GPT-5 and GPT-4o can analyze and discuss images. Here are examples of how to upload images to\nchat:\n\n#### Upload Image from File\n\n```php\n\u003c?php\n\nuse Tigusigalpa\\MonicaAI\\MonicaClient;\nuse Tigusigalpa\\MonicaAI\\Models\\ChatMessage;\n\n// GPT-5 provides the most advanced image analysis capabilities\n$client = new MonicaClient('your-api-key', 'gpt-5');\n\n// Create a message with image from file\n$message = ChatMessage::userWithImage(\n    'What do you see in this image?',\n    'path/to/your/image.jpg'\n);\n\n// Alternative: Add image to existing message\n$message = ChatMessage::user('Analyze this image for me');\n$message-\u003eaddImageFromFile('path/to/your/image.jpg', 'high'); // detail level: low, high, auto\n\n$response = $client-\u003echatWithMessages([$message]);\necho $response-\u003egetContent();\n```\n\n#### Upload Image from URL\n\n```php\n// Create message with image from URL\n$message = ChatMessage::userWithImage(\n    'Describe what you see in this photo',\n    'https://example.com/image.jpg'\n);\n\n$response = $client-\u003echatWithMessages([$message]);\necho $response-\u003egetContent();\n```\n\n#### Upload Multiple Images\n\n```php\n// Upload multiple images at once\n$imageUrls = [\n    'https://example.com/image1.jpg',\n    'https://example.com/image2.jpg',\n    'path/to/local/image3.png'\n];\n\n$message = ChatMessage::userWithImages(\n    'Compare these images and tell me the differences',\n    $imageUrls\n);\n\n$response = $client-\u003echatWithMessages([$message]);\necho $response-\u003egetContent();\n```\n\n#### Upload Image from Base64\n\n```php\n// Upload image from base64 data\n$base64ImageData = base64_encode(file_get_contents('image.jpg'));\n\n$message = ChatMessage::user('What breed is this dog?');\n$message-\u003eaddImageFromBase64($base64ImageData, 'image/jpeg', 'high');\n\n$response = $client-\u003echatWithMessages([$message]);\necho $response-\u003egetContent();\n```\n\n#### Advanced Image Chat Example\n\n```php\nuse Tigusigalpa\\MonicaAI\\Models\\ChatMessage;\n\n$messages = [\n    ChatMessage::system('You are an expert art critic and historian.'),\n    ChatMessage::userWithImage(\n        'Please analyze this painting in detail',\n        'path/to/painting.jpg'\n    )\n];\n\n$response = $client-\u003echatWithMessages($messages, [\n    'temperature' =\u003e 0.7,\n    'max_tokens' =\u003e 1500\n]);\n\necho \"Art Analysis: \" . $response-\u003egetContent();\n\n// Continue the conversation with follow-up questions\n$messages[] = ChatMessage::assistant($response-\u003egetContent());\n$messages[] = ChatMessage::user('What art movement does this belong to?');\n\n$followUp = $client-\u003echatWithMessages($messages);\necho \"Art Movement: \" . $followUp-\u003egetContent();\n```\n\n#### Working with Image Details\n\n```php\n// Control image processing detail level\n$message = ChatMessage::user('Examine this image closely');\n$message-\u003eaddImageFromFile('detailed_image.jpg', 'high'); // More detailed analysis\n// or\n$message-\u003eaddImageFromFile('simple_image.jpg', 'low');   // Faster, less detailed\n\n// Check if message has images\nif ($message-\u003ehasImages()) {\n    echo \"Message contains \" . count($message-\u003egetImages()) . \" images\";\n}\n\n// Get image information\n$images = $message-\u003egetImages();\nforeach ($images as $image) {\n    echo \"Image URL: \" . $image['image_url']['url'] . \"\\n\";\n    echo \"Detail level: \" . $image['image_url']['detail'] . \"\\n\";\n}\n```\n\n#### Supported Vision Models\n\nThe following models support image analysis:\n\n- **GPT-5**: Most advanced image analysis and understanding capabilities\n- **GPT-4o**: Excellent for detailed image analysis and understanding\n- **GPT-4o Mini**: Faster, cost-effective option for basic image tasks\n\n### Creating Messages from Array Data\n\nYou can create `ChatMessage` instances directly from array data using the `fromArray()` method. This is particularly\nuseful when working with pre-structured message data or when integrating with existing systems that use\nOpenAI-compatible message formats.\n\n#### Basic Usage\n\n```php\n// Create a simple text message from array\n$messageData = [\n    'role' =\u003e 'user',\n    'content' =\u003e 'Hello, how are you today?'\n];\n\n$message = ChatMessage::fromArray($messageData);\n$response = $client-\u003echatWithMessages([$message]);\n```\n\n#### Multimodal Messages with Mixed Content\n\n```php\n// Create a complex multimodal message with text and images\n$messageData = [\n    'role' =\u003e 'user',\n    'content' =\u003e [\n        [\n            'type' =\u003e 'text',\n            'text' =\u003e 'Please solve this equation step by step:'\n        ],\n        [\n            'type' =\u003e 'image_url',\n            'image_url' =\u003e [\n                'url' =\u003e 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...',\n                'detail' =\u003e 'high'\n            ]\n        ],\n        [\n            'type' =\u003e 'text',\n            'text' =\u003e 'Show all intermediate steps in your solution.'\n        ],\n        [\n            'type' =\u003e 'image_url',\n            'image_url' =\u003e [\n                'url' =\u003e 'https://example.com/reference-image.png',\n                'detail' =\u003e 'auto'\n            ]\n        ]\n    ]\n];\n\n$message = ChatMessage::fromArray($messageData);\n$response = $client-\u003echatWithMessages([$message]);\necho $response-\u003egetContent();\n```\n\n#### Working with Conversation Arrays\n\n```php\n// Create multiple messages from array data\n$conversationData = [\n    [\n        'role' =\u003e 'system',\n        'content' =\u003e 'You are a helpful math tutor.'\n    ],\n    [\n        'role' =\u003e 'user',\n        'content' =\u003e [\n            [\n                'type' =\u003e 'text',\n                'text' =\u003e 'Help me understand this problem:'\n            ],\n            [\n                'type' =\u003e 'image_url',\n                'image_url' =\u003e [\n                    'url' =\u003e 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...',\n                    'detail' =\u003e 'high'\n                ]\n            ]\n        ]\n    ]\n];\n\n// Convert array data to ChatMessage objects\n$messages = array_map(function($messageData) {\n    return ChatMessage::fromArray($messageData);\n}, $conversationData);\n\n$response = $client-\u003echatWithMessages($messages);\necho $response-\u003egetContent();\n```\n\n#### Helper Function for Batch Processing\n\n```php\n/**\n * Convert an array of message data to ChatMessage objects\n */\nfunction createMessagesFromArray(array $messagesData): array\n{\n    return array_map(function($messageData) {\n        return ChatMessage::fromArray($messageData);\n    }, $messagesData);\n}\n\n// Usage\n$messagesData = [\n    ['role' =\u003e 'system', 'content' =\u003e 'You are an expert assistant.'],\n    ['role' =\u003e 'user', 'content' =\u003e 'What is the capital of France?'],\n    ['role' =\u003e 'assistant', 'content' =\u003e 'The capital of France is Paris.'],\n    ['role' =\u003e 'user', 'content' =\u003e 'Tell me more about it.']\n];\n\n$messages = createMessagesFromArray($messagesData);\n$response = $client-\u003echatWithMessages($messages);\n```\n\n#### Supported Array Structure\n\nThe `fromArray()` method supports the following message structure:\n\n```php\n[\n    'role' =\u003e 'user|assistant|system',           // Required: Message role\n    'content' =\u003e 'string' | [                   // Required: Message content\n        [\n            'type' =\u003e 'text',\n            'text' =\u003e 'Text content here'\n        ],\n        [\n            'type' =\u003e 'image_url',\n            'image_url' =\u003e [\n                'url' =\u003e 'https://... or data:image/...',  // Image URL or base64 data URL\n                'detail' =\u003e 'low|high|auto'                // Optional: Detail level\n            ]\n        ]\n    ],\n    'name' =\u003e 'optional_message_name'           // Optional: Message name\n]\n```\n\n## 🎨 Image Generation Usage\n\n### Simple Image Generation\n\n```php\n\u003c?php\n\nuse Tigusigalpa\\MonicaAI\\MonicaClient;\n\n$client = new MonicaClient('your-api-key', 'gpt-5');\n\n// Generate a single image with FLUX\n$response = $client-\u003egenerateImageSimple(\n    'flux_dev',\n    'A beautiful sunset over mountains, digital art style',\n    [\n        'size' =\u003e '1024x1024',\n        'steps' =\u003e 25,\n        'guidance' =\u003e 3.5,\n        'seed' =\u003e 42\n    ]\n);\n\necho \"Generated image URL: \" . $response-\u003egetFirstImageUrl();\n\n// Save the image\n$response-\u003esaveFirstImage('sunset.png');\n```\n\n### Advanced Image Generation\n\n```php\n\u003c?php\n\nuse Tigusigalpa\\MonicaAI\\Models\\ImageGeneration;\n\n// Create detailed image generation request\n$imageGen = new ImageGeneration('sd3_5', 'A majestic dragon flying over a medieval castle');\n$imageGen-\u003esetNegativePrompt('blurry, low quality, distorted')\n         -\u003esetSize('1024x1024')\n         -\u003esetSteps(30)\n         -\u003esetCfgScale(7.5)\n         -\u003esetSeed(123);\n\n$response = $client-\u003egenerateImage($imageGen);\n\n// Work with multiple images\nforeach ($response-\u003egetImageUrls() as $index =\u003e $url) {\n    echo \"Image \" . ($index + 1) . \": {$url}\\n\";\n}\n\n// Save all images to directory\n$savedFiles = $response-\u003esaveAllImages('./images/', 'dragon_', 'png');\n```\n\n### Model-Specific Examples\n\n#### DALL·E 3 with Quality Options\n\n```php\n$response = $client-\u003egenerateImageSimple(\n    'dall-e-3',\n    'A cute robot playing with colorful balloons in a park',\n    [\n        'size' =\u003e '1024x1024',\n        'quality' =\u003e 'hd',\n        'style' =\u003e 'vivid'\n    ]\n);\n```\n\n#### Ideogram V2 for Text and Logos\n\n```php\n$imageGen = new ImageGeneration('V_2', 'Logo design for \"TECH STARTUP\" with modern typography');\n$imageGen-\u003esetAspectRatio('ASPECT_16_9')\n         -\u003esetMagicPromptOption('AUTO')\n         -\u003esetStyleType('AUTO');\n\n$response = $client-\u003egenerateImage($imageGen);\n```\n\n#### Playground V2.5 with Multiple Outputs\n\n```php\n$response = $client-\u003egenerateImageSimple(\n    'playground-v2-5',\n    'Abstract geometric patterns in vibrant colors',\n    [\n        'count' =\u003e 3,\n        'size' =\u003e '1024x1024',\n        'step' =\u003e 30,\n        'cfg_scale' =\u003e 7.0\n    ]\n);\n```\n\n### Model Management\n\n```php\n// Check if a model is supported\nif ($client-\u003eisModelSupported('gpt-5')) {\n    $client-\u003esetModel('gpt-5');\n}\n\n// Get all supported models\n$models = MonicaClient::getSupportedModels();\nforeach ($models as $provider =\u003e $providerModels) {\n    echo \"Provider: $provider\\n\";\n    foreach ($providerModels as $modelId =\u003e $modelName) {\n        echo \"  - $modelId: $modelName\\n\";\n    }\n}\n\n// Get models by specific provider\n$openaiModels = MonicaClient::getModelsByProvider('OpenAI');\n```\n\n### Error Handling\n\n```php\ntry {\n    $response = $client-\u003echat('Hello world');\n} catch (InvalidModelException $e) {\n    // Handle invalid model errors\n    echo \"Model error: \" . $e-\u003egetUserFriendlyMessage();\n    \n    // Get suggestions for similar models\n    $suggestions = $e-\u003egetSuggestions();\n    if (!empty($suggestions)) {\n        echo \"Did you mean: \" . implode(', ', $suggestions);\n    }\n    \n} catch (MonicaAIException $e) {\n    // Handle API errors\n    if ($e-\u003eisAuthenticationError()) {\n        echo \"Please check your API key\";\n    } elseif ($e-\u003eisRateLimitError()) {\n        echo \"Rate limit exceeded, please wait\";\n    } elseif ($e-\u003eisQuotaError()) {\n        echo \"API quota exceeded\";\n    } else {\n        echo \"API Error: \" . $e-\u003egetUserFriendlyMessage();\n    }\n}\n```\n\n### Working with Response Data\n\n```php\n$response = $client-\u003echat('Tell me a joke');\n\n// Get response content\necho $response-\u003egetContent();\n\n// Get usage statistics\necho \"Tokens used: \" . $response-\u003egetTotalTokens() . \"\\n\";\necho \"Prompt tokens: \" . $response-\u003egetPromptTokens() . \"\\n\";\necho \"Completion tokens: \" . $response-\u003egetCompletionTokens() . \"\\n\";\n\n// Check completion status\nif ($response-\u003eisComplete()) {\n    echo \"Response completed normally\";\n} elseif ($response-\u003ewasTruncated()) {\n    echo \"Response was truncated due to length limit\";\n} elseif ($response-\u003ewasFiltered()) {\n    echo \"Response was filtered due to content policy\";\n}\n\n// Get response as ChatMessage object\n$message = $response-\u003egetFirstChoiceAsMessage();\nif ($message) {\n    echo $message-\u003egetRole() . \": \" . $message-\u003egetContent();\n}\n```\n\n## 🔧 Configuration Options\n\n### Chat Completion Parameters\n\n| Parameter           | Type   | Description                           | Range           |\n|---------------------|--------|---------------------------------------|-----------------|\n| `system`            | string | System message to set AI behavior     | -               |\n| `temperature`       | float  | Controls randomness in responses      | 0.0 - 2.0       |\n| `max_tokens`        | int    | Maximum tokens in response            | 1 - model limit |\n| `top_p`             | float  | Nucleus sampling parameter            | 0.0 - 1.0       |\n| `frequency_penalty` | float  | Reduces repetition of frequent tokens | -2.0 - 2.0      |\n| `presence_penalty`  | float  | Reduces repetition of any tokens      | -2.0 - 2.0      |\n\n### Example with All Parameters\n\n```php\n$response = $client-\u003echat('Write a poem about nature', [\n    'system' =\u003e 'You are a poetic AI that writes beautiful verses',\n    'temperature' =\u003e 0.7,\n    'max_tokens' =\u003e 300,\n    'top_p' =\u003e 0.9,\n    'frequency_penalty' =\u003e 0.1,\n    'presence_penalty' =\u003e 0.1\n]);\n```\n\n## 🏗 Laravel Integration\n\n### Service Provider Registration\n\n```php\n// config/app.php\n'providers' =\u003e [\n    // ...\n    App\\Providers\\MonicaServiceProvider::class,\n],\n```\n\n### Service Provider Example\n\n```php\n\u003c?php\n\nnamespace App\\Providers;\n\nuse Illuminate\\Support\\ServiceProvider;\nuse Tigusigalpa\\MonicaAI\\MonicaClient;\n\nclass MonicaServiceProvider extends ServiceProvider\n{\n    public function register()\n    {\n        $this-\u003eapp-\u003esingleton(MonicaClient::class, function ($app) {\n            return new MonicaClient(\n                config('services.monica.api_key'),\n                config('services.monica.default_model', 'gpt-5')\n            );\n        });\n    }\n}\n```\n\n### Configuration\n\n```php\n// config/services.php\n'monica' =\u003e [\n    'api_key' =\u003e env('MONICA_API_KEY'),\n    'default_model' =\u003e env('MONICA_DEFAULT_MODEL', 'gpt-5'),\n],\n```\n\n### Environment Variables\n\n```bash\n# .env\nMONICA_API_KEY=your-monica-api-key-here\nMONICA_DEFAULT_MODEL=gpt-5\n```\n\n### Controller Example\n\n```php\n\u003c?php\n\nnamespace App\\Http\\Controllers;\n\nuse Illuminate\\Http\\Request;\nuse Tigusigalpa\\MonicaAI\\MonicaClient;\nuse Tigusigalpa\\MonicaAI\\Exceptions\\MonicaAIException;\n\nclass ChatController extends Controller\n{\n    public function __construct(\n        private MonicaClient $monica\n    ) {}\n\n    public function chat(Request $request)\n    {\n        $request-\u003evalidate([\n            'message' =\u003e 'required|string|max:4000',\n            'model' =\u003e 'sometimes|string',\n        ]);\n\n        try {\n            if ($request-\u003ehas('model')) {\n                $this-\u003emonica-\u003esetModel($request-\u003emodel);\n            }\n\n            $response = $this-\u003emonica-\u003echat($request-\u003emessage);\n\n            return response()-\u003ejson([\n                'success' =\u003e true,\n                'response' =\u003e $response-\u003egetContent(),\n                'model' =\u003e $this-\u003emonica-\u003egetModel(),\n                'tokens_used' =\u003e $response-\u003egetTotalTokens(),\n            ]);\n\n        } catch (MonicaAIException $e) {\n            return response()-\u003ejson([\n                'success' =\u003e false,\n                'error' =\u003e $e-\u003egetUserFriendlyMessage(),\n            ], 500);\n        }\n    }\n}\n```\n\n## 🧪 Testing\n\nRun the test suite:\n\n```bash\ncomposer test\n```\n\nRun with coverage:\n\n```bash\ncomposer test:coverage\n```\n\n## 📚 API Reference\n\n### MonicaClient\n\n#### Constructor\n\n```php\nnew MonicaClient(string $apiKey, string $model)\n```\n\n#### Methods\n\n- `chat(string $message, array $options = []): ChatCompletionResponse`\n- `chatWithMessages(ChatMessage[] $messages, array $options = []): ChatCompletionResponse`\n- `generateImage(ImageGeneration $imageGeneration): ImageGenerationResponse`\n- `generateImageSimple(string $model, string $prompt, array $options = []): ImageGenerationResponse`\n- `setModel(string $model): void`\n- `getModel(): string`\n- `isModelSupported(string $model): bool`\n- `static getSupportedModels(): array`\n- `static getModelsByProvider(string $provider): array`\n- `static getAllModelIds(): array`\n- `static getSupportedImageModels(): array`\n\n### ChatMessage\n\n#### Static Constructors\n\n- `ChatMessage::system(string $content, ?string $name = null): ChatMessage`\n- `ChatMessage::user(string $content, ?string $name = null): ChatMessage`\n- `ChatMessage::assistant(string $content, ?string $name = null): ChatMessage`\n- `ChatMessage::userWithImage(string $content, string $imageUrl): ChatMessage`\n- `ChatMessage::userWithImages(string $content, array $imageUrls): ChatMessage`\n- `ChatMessage::fromArray(array $data): ChatMessage`\n\n#### Methods\n\n- `getRole(): string`\n- `getContent(): string`\n- `getName(): ?string`\n- `isSystem(): bool`\n- `isUser(): bool`\n- `isAssistant(): bool`\n- `hasImages(): bool`\n- `getImages(): array`\n- `addImageFromFile(string $filePath, string $detail = 'auto'): self`\n- `addImageFromUrl(string $url, string $detail = 'auto'): self`\n- `addImageFromBase64(string $base64Data, string $mimeType, string $detail = 'auto'): self`\n- `toArray(): array`\n\n### ChatCompletionResponse\n\n#### Methods\n\n- `getContent(): string`\n- `getRole(): string`\n- `getFinishReason(): ?string`\n- `getTotalTokens(): int`\n- `getPromptTokens(): int`\n- `getCompletionTokens(): int`\n- `isComplete(): bool`\n- `wasTruncated(): bool`\n- `wasFiltered(): bool`\n- `getFirstChoice(): ?array`\n- `getFirstChoiceAsMessage(): ?ChatMessage`\n- `getAllChoices(): array`\n\n### ImageGeneration\n\n#### Constructor\n\n```php\nnew ImageGeneration(string $model, string $prompt)\n```\n\n#### Methods\n\n- `getModel(): string`\n- `getPrompt(): string`\n- `setNegativePrompt(string $negativePrompt): self`\n- `setNumOutputs(int $numOutputs): self`\n- `setSize(string $size): self`\n- `setSeed(int $seed): self`\n- `setSteps(int $steps): self`\n- `setGuidance(float $guidance): self`\n- `setCfgScale(float $cfgScale): self`\n- `setQuality(string $quality): self`\n- `setStyle(string $style): self`\n- `setAspectRatio(string $aspectRatio): self`\n- `setMagicPromptOption(string $option): self`\n- `setStyleType(string $styleType): self`\n- `setSafetyTolerance(int $tolerance): self`\n- `static isModelSupported(string $model): bool`\n- `static getSupportedModels(): array`\n- `toArray(): array`\n\n### ImageGenerationResponse\n\n#### Methods\n\n- `getImageUrls(): array`\n- `getFirstImageUrl(): ?string`\n- `saveFirstImage(string $filePath): bool`\n- `saveAllImages(string $directory, string $prefix = 'image_', string $extension = 'png'): array`\n- `getImageCount(): int`\n\n## 📝 Changelog\n\n### [Unreleased]\n\n#### Added\n\n- **GPT-5 Support**: Added support for OpenAI's latest flagship model `gpt-5`\n    - Full chat completion capabilities with advanced reasoning\n    - Enhanced image analysis and multimodal understanding\n    - Updated default model examples to showcase GPT-5\n    - Added GPT-5 to supported vision models list\n\n#### Changed\n\n- Updated Quick Start example to use GPT-5 as the default model\n- Enhanced Laravel integration examples with GPT-5 configuration\n- Updated model comparison tables to highlight GPT-5 capabilities\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to\ndiscuss what you would like to change.\n\n### Development Setup\n\n1. Clone the repository\n2. Install dependencies: `composer install`\n3. Run tests: `composer test`\n4. Check code style: `composer cs-check`\n5. Fix code style: `composer cs-fix`\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🔗 Links\n\n- [Monica API Platform](https://platform.monica.im/)\n- [API Documentation](https://platform.monica.im/docs/en/overview)\n- [GitHub Repository](https://github.com/tigusigalpa/monica-ai-php)\n- [Packagist](https://packagist.org/packages/tigusigalpa/monica-ai-php)\n\n## 💬 Support\n\nIf you have any questions or need help, please:\n\n1. Check the [documentation](https://platform.monica.im/docs/en/overview)\n2. Search existing [GitHub issues](https://github.com/tigusigalpa/monica-ai-php/issues)\n3. Create a new issue if needed\n\n## 🙏 Acknowledgments\n\n- [Monica API Platform](https://platform.monica.im/) for providing the unified AI API\n- All the AI providers (OpenAI, Anthropic, Google, etc.) for their amazing models\n- The PHP community for excellent tools and libraries\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftigusigalpa%2Fmonica-ai-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftigusigalpa%2Fmonica-ai-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftigusigalpa%2Fmonica-ai-php/lists"}