Merge pull request #64 from moe-mizrak/feat/add-input-audio

Feat/add input audio

Author: moe-mizrak

README.md

@@ -29,6 +29,7 @@ This Laravel package provides an easy-to-use interface for integrating **[OpenRo
       - [Stream Chat Request](#stream-chat-request)
       - [Maintaining Conversation Continuity](#maintaining-conversation-continuity)
       - [Structured Output](#structured-output)
+      - [Audio Inputs](#audio-inputs)
     - [Cost Request](#cost-request)
     - [Limit Request](#limit-request)
   - [Using OpenRouterRequest Class](#using-openrouterrequest-class)
@@ -536,6 +537,51 @@ $chatData = new ChatData(
 > [!TIP]
 > You can also use **prompt engineering** to obtain structured output and control the format of responses.
 
+- ####  Audio Inputs
+  (Please also refer to [OpenRouter Document Audio Inputs](https://openrouter.ai/docs/features/multimodal/audio) for models supporting audio inputs, also for more details)
+
+Audio input is supported by some models in OpenRouter. You can provide audio input by using the `AudioContentData` DTO class as following:
+
+```php
+$model = 'mistralai/voxtral-small-24b-2507'; // Audio input supported models: https://openrouter.ai/models?fmt=cards&input_modalities=audio
+$data = base64_encode('path/of/audio/file.mp3'); // Base64-encoded audio data
+
+$audioContentData = new AudioContentData(
+    type: AudioContentData::ALLOWED_TYPE, // it can only take input_audio for audio content
+    input_audio: new InputAudioData(
+        data: $data,
+        format: AudioFormatType::MP3, // Supported formats: mp3, wav
+    ),
+);
+
+$textContentData = new TextContentData(
+    type: TextContentData::ALLOWED_TYPE,
+    text: 'Please transcribe this audio file.',
+);
+
+$messageData = new MessageData(
+    content: [
+        $textContentData,
+        $audioContentData,
+    ],
+    role: RoleType::USER,
+);
+
+$chatData = new ChatData(
+    messages: [
+        $messageData,
+    ],
+    model: $model,
+);
+
+$response = LaravelOpenRouter::chatRequest($chatData);
+```
+
+> [!NOTE]
+> Only `mp3` and `wav` formats are supported for audio inputs.
+> 
+> And make sure to provide valid `base64-encoded` audio data.
+
 #### Cost Request
 
 To retrieve the cost of a generation, first make a `chat request` and obtain the `generationId`. Then, pass the generationId to the `costRequest` method:

src/DTO/AudioContentData.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MoeMizrak\LaravelOpenrouter\DTO;
+
+use MoeMizrak\LaravelOpenrouter\Rules\AllowedValues;
+
+/**
+ * DTO for the audio contents.
+ *
+ * Class AudioContentData
+ * @package MoeMizrak\LaravelOpenrouter\DTO
+ */
+final class AudioContentData extends DataTransferObject
+{
+    /**
+     * The allowed type for image content.
+     */
+    public const ALLOWED_TYPE = 'input_audio';
+
+    /**
+     * @inheritDoc
+     */
+    public function __construct(
+        /**
+         * Type of the content. (i.e. input_audio)
+         *
+         * @var string
+         */
+        #[AllowedValues([self::ALLOWED_TYPE])]
+        public string $type = self::ALLOWED_TYPE,
+
+        /**
+         * DTO of input audio.
+         *
+         * @var InputAudioData
+         */
+        public InputAudioData $input_audio
+    ) {
+        parent::__construct(...func_get_args());
+    }
+
+    /**
+     * @return array
+     */
+    public function convertToArray(): array
+    {
+        return array_filter(
+            [
+                'type' => $this->type,
+                'input_audio' => $this->input_audio?->convertToArray(),
+            ],
+            fn($value) => $value !== null
+        );
+    }
+}

src/DTO/InputAudioData.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MoeMizrak\LaravelOpenrouter\DTO;
+
+/**
+ * DTO for the input audio which are data and format for the audio.
+ *
+ * Class InputAudioData
+ * @package MoeMizrak\LaravelOpenrouter\DTO
+ */
+final class InputAudioData extends DataTransferObject
+{
+    /**
+     * @inheritDoc
+     */
+    public function __construct(
+        /**
+         * base64 encoded audio data
+         *
+         * @var string
+         */
+        public string $data,
+
+        /**
+         * Optional, detail about the audio format
+         * Supported audio formats are: mp3, wav.
+         *
+         * @var string|null
+         */
+        public ?string $format = null
+    ) {
+        parent::__construct(...func_get_args());
+    }
+
+    /**
+     * @return array
+     */
+    public function convertToArray(): array
+    {
+        return array_filter(
+            [
+                'data' => $this->data,
+                'format' => $this->format,
+            ],
+            fn($value) => $value !== null
+        );
+    }
+}

src/Types/AudioFormatType.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MoeMizrak\LaravelOpenrouter\Types;
+
+/**
+ * Audio can be provided in different formats for now: mp3, wav.
+ * See: https://openrouter.ai/docs/features/multimodal/audio
+ *
+ * Class AudioFormatType
+ * @package MoeMizrak\LaravelOpenrouter\Types
+ */
+final readonly class AudioFormatType
+{
+    /**
+     * MP3 audio format
+     *
+     * @var string
+     */
+    const MP3 = 'mp3';
+
+    /**
+     * WAV audio format
+     *
+     * @var string
+     */
+    const WAV = 'wav';
+}

tests/OpenRouterAPITest.php

@@ -6,10 +6,12 @@
 use GuzzleHttp\Psr7\Response;
 use Illuminate\Support\Arr;
 use Mockery\MockInterface;
+use MoeMizrak\LaravelOpenrouter\DTO\AudioContentData;
 use MoeMizrak\LaravelOpenrouter\DTO\ChatData;
 use MoeMizrak\LaravelOpenrouter\DTO\CostResponseData;
 use MoeMizrak\LaravelOpenrouter\DTO\ImageContentPartData;
 use MoeMizrak\LaravelOpenrouter\DTO\ImageUrlData;
+use MoeMizrak\LaravelOpenrouter\DTO\InputAudioData;
 use MoeMizrak\LaravelOpenrouter\DTO\LimitResponseData;
 use MoeMizrak\LaravelOpenrouter\DTO\MessageData;
 use MoeMizrak\LaravelOpenrouter\DTO\ProviderPreferencesData;
@@ -20,6 +22,7 @@
 use MoeMizrak\LaravelOpenrouter\Exceptions\OpenRouterValidationException;
 use MoeMizrak\LaravelOpenrouter\Facades\LaravelOpenRouter;
 use MoeMizrak\LaravelOpenrouter\OpenRouterRequest;
+use MoeMizrak\LaravelOpenrouter\Types\AudioFormatType;
 use MoeMizrak\LaravelOpenrouter\Types\DataCollectionType;
 use MoeMizrak\LaravelOpenrouter\Types\EffortType;
 use MoeMizrak\LaravelOpenrouter\Types\RoleType;
@@ -538,6 +541,43 @@ public function it_successfully_sends_image_and_text_content_in_messages_in_the_
         $this->assertNotNull(Arr::get($response->choices[0], 'message.content'));
     }
 
+    // test for the audio content
+    #[Test]
+    public function it_successfully_sends_audio_in_content_in_messages_in_the_open_route_api_request()
+    {
+        /* SETUP */
+        $data = base64_encode('fake-audio-data'); // Simulated base64 audio data
+        $audioContentData = new AudioContentData(
+            type: AudioContentData::ALLOWED_TYPE, // it can only take input_audio for audio content
+            input_audio: new InputAudioData(
+                data: $data,
+                format: AudioFormatType::MP3,
+            ),
+        );
+        $messageData = new MessageData(
+            content: [
+                $audioContentData,
+            ],
+            role: RoleType::USER,
+        );
+        $chatData = new ChatData(
+            messages: [
+                $messageData,
+            ],
+            model: $this->model,
+            max_tokens: $this->maxTokens,
+        );
+        $this->mockOpenRouter($this->mockBasicBody());
+
+        /* EXECUTE */
+        $response = $this->api->chatRequest($chatData);
+
+        /* ASSERT */
+        $this->generalTestAssertions($response);
+        $this->assertEquals(RoleType::ASSISTANT, Arr::get($response->choices[0], 'message.role'));
+        $this->assertNotNull(Arr::get($response->choices[0], 'message.content'));
+    }
+
     #[Test]
     public function it_successfully_sends_multiple_text_content_in_messages_in_the_open_route_api_request()
     {