README

Laravel Client for Mistral.AI

The Mistral.ai Laravel Client enables laravel applications to interact with the Mistral.ai API, providing straightforward access to features like chat completions and text embeddings.

Get your API key at console.mistral.ai.

Installation

You can install the package via composer:

composer require helgesverre/mistral

You can publish the config file with:

php artisan vendor:publish --tag="mistral-config"

This is the contents of the published config file:

return [
    'api_key' => env('MISTRAL_API_KEY'),
    'base_url' => env('MISTRAL_BASE_URL'), // defaults to https://api.mistral.ai/v1 if null
    'timeout' => env('MISTRAL_TIMEOUT', 60),
];

Usage

Client Instantiation

Create an instance of the Mistral client to start interacting with the API. This instance will be your primary interface for sending requests to Mistral.AI.

use HelgeSverre\Mistral\Enums\Model;
use HelgeSverre\Mistral\Mistral;

// Instantiate the client
$mistral = new Mistral(apiKey: config('mistral.api_key'));

// Or use the Facade (Laravel)
Mistral::chat();
Mistral::simpleChat();
Mistral::embedding();
Mistral::models();

Examples

The package includes 12 hands-on examples in the examples/ directory, each with detailed documentation, working code, and explanations. These examples are the fastest way to learn the SDK and see it in action.

Quick Start: Begin with 01-getting-started to set up your first working integration.

Each example includes:

• Step-by-step implementation guide
• Complete working code
• Real-world use cases
• Troubleshooting tips
• Links to related examples

To run an example:

cd examples/01-getting-started
php getting-started.php

Available Resources & Methods

The Mistral PHP client provides 14 resource classes. Most resources offer both Response-returning methods and typed DTO convenience methods; where omitted, you can still call ->dto() on the Response.

Chat Resource

Access via $mistral->chat()

Methods:

• create(...): Response - Create a chat completion
• createDto(...): ChatCompletionResponse - Create a chat completion and return typed DTO
• createStreamed(...): Generator - Stream chat completions

Example:

$completion = $mistral->chat()->createDto(
    messages: [['role' => 'user', 'content' => 'Hello!']],
    model: Model::small->value
);

SimpleChat Resource

Access via $mistral->simpleChat()

Methods:

• create(...): SimpleChatResponse - Simplified chat completion (returns flattened DTO directly)
• stream(...): Generator - Stream simplified chat completions

Example:

$response = $mistral->simpleChat()->create(
    messages: [['role' => 'user', 'content' => 'Hello!']],
    model: Model::medium->value
);
echo $response->content; // Direct access to content

Embedding Resource

Access via $mistral->embedding()

Methods:

• create(array $input, ...): Response - Create embeddings
• createDto(array $input, ...): EmbeddingResponse - Create embeddings and return typed DTO

Example:

$embeddings = $mistral->embedding()->createDto([
    'Text to embed',
    'Another text'
]);

Models Resource

Access via $mistral->models()

Methods:

• list(): Response - List available models
• listDto(): ModelList - List models and return typed DTO
• retrieve(string $modelId): BaseModelCard|FTModelCard - Get model details
• delete(string $modelId): DeleteModelOut - Delete a fine-tuned model

Example:

$models = $mistral->models()->listDto();
foreach ($models->data as $model) {
    echo $model->id;
}

OCR Resource

Access via $mistral->ocr()

Methods:

• process(...): Response - Process document with OCR
• processDto(...): OCRResponse - Process and return typed DTO
• processUrl(string $url, ...): Response - Process document from URL
• processUrlDto(string $url, ...): OCRResponse - Process URL and return typed DTO
• processBase64(string $base64, ...): Response - Process base64 encoded document
• processBase64Dto(string $base64, ...): OCRResponse - Process base64 and return typed DTO

Example:

$result = $mistral->ocr()->processUrlDto(
    url: 'https://example.com/document.pdf'
);

FIM Resource (Fill-in-the-Middle)

Access via $mistral->fim()

Methods:

• create(...): Response - Create FIM completion
• createDto(...): FIMCompletionResponse - Create and return typed DTO
• createStreamed(...): Generator - Stream FIM completions

Example:

$completion = $mistral->fim()->createDto(
    model: 'codestral-latest',
    prompt: 'def fibonacci(',
    suffix: '    return result'
);

Agents Resource

Access via $mistral->agents()

Methods:

• create(AgentCreationRequest $request): Response - Create an agent
• createDto(AgentCreationRequest $request): Agent - Create and return typed DTO
• list(?int $page, ?int $pageSize): Response - List agents
• listDto(?int $page, ?int $pageSize): AgentList - List and return typed DTO
• get(string $agentId): Response - Get agent details
• getDto(string $agentId): Agent - Get agent and return typed DTO
• update(string $agentId, AgentUpdateRequest $request): Response - Update agent
• updateDto(string $agentId, AgentUpdateRequest $request): Agent - Update and return typed DTO
• updateVersion(string $agentId, int $version): Response - Switch agent version
• updateVersionDto(string $agentId, int $version): Agent - Switch version and return typed DTO
• listVersions(string $agentId, ?int $page, ?int $pageSize): Response - List all versions of an agent
• listVersionsDto(...): DataCollection<Agent> - List versions and return typed DTO collection
• getVersion(string $agentId, int $version): Response - Get a specific agent version
• getVersionDto(string $agentId, int $version): Agent - Get version and return typed DTO
• listAliases(string $agentId): Response - List all aliases for an agent
• listAliasesDto(string $agentId): DataCollection<AgentAliasResponse> - List aliases and return typed DTO collection
• createAlias(string $agentId, string $alias, int $version): Response - Create or update an alias (idempotent PUT)
• createAliasDto(...): AgentAliasResponse - Create/update alias and return typed DTO
• deleteAlias(string $agentId, string $alias): Response - Delete an alias (204 No Content)

Conversations Resource

Access via $mistral->conversations()

Methods:

• create(ConversationRequest $request): Response - Create conversation
• createDto(ConversationRequest $request): ConversationResponse - Create and return typed DTO
• createStreamed(ConversationRequest $request): Generator - Create with streaming
• list(?int $page, ?int $pageSize, ?string $order): Response - List conversations
• listDto(...): ConversationList - List and return typed DTO
• get(string $conversationId): Response - Get conversation
• getDto(string $conversationId): ConversationResponse - Get and return typed DTO
• append(string $conversationId, ConversationAppendRequest $request): Response - Append to conversation
• appendDto(...): ConversationResponse - Append and return typed DTO
• appendStreamed(...): Generator - Append with streaming
• getHistory(string $conversationId): Response - Get conversation history
• getHistoryDto(string $conversationId): ConversationHistory - Get history and return typed DTO
• getMessages(string $conversationId): Response - Get conversation messages
• getMessagesDto(string $conversationId): ConversationMessages - Get messages and return typed DTO
• restart(string $conversationId, ConversationRestartRequest $request): Response - Restart conversation
• restartDto(...): ConversationResponse - Restart and return typed DTO
• restartStreamed(...): Generator - Restart with streaming

Audio Resource

Access via $mistral->audio()

Methods:

Transcription (speech-to-text):

• transcribe(string $filePath, ...): Response - Transcribe audio
• transcribeDto(string $filePath, ...): TranscriptionResponse - Transcribe and return typed DTO
• transcribeStreamed(string $filePath, ...): Generator - Transcribe with streaming

Speech (text-to-speech):

• speech(SpeechRequest $request): Response - Generate speech audio
• speechDto(SpeechRequest $request): SpeechResponse - Generate speech and return typed DTO (base64 audio + decoded() / saveTo() helpers)
• speechStreamed(SpeechRequest $request): Generator - Stream audio chunks (SpeechStreamAudioDelta + final SpeechStreamDone)

Voices:

• listVoices(?int $limit, ?int $offset): Response - List voices (paginated)
• listVoicesDto(...): VoiceListResponse
• createVoice(VoiceCreateRequest $request): Response - Create a custom voice (use VoiceCreateRequest::fromFile() to load + base64 a local file)
• createVoiceDto(...): VoiceResponse
• getVoice(string $voiceId): Response - Get a voice
• getVoiceDto(string $voiceId): VoiceResponse
• updateVoice(string $voiceId, VoiceUpdateRequest $request): Response - Update voice metadata
• updateVoiceDto(...): VoiceResponse
• deleteVoice(string $voiceId): Response - Delete a custom voice (returns the deleted voice)
• deleteVoiceDto(string $voiceId): VoiceResponse
• getVoiceSample(string $voiceId): Response - Download the raw audio/wav sample for a voice

Example — transcription:

$transcription = $mistral->audio()->transcribeDto(
    filePath: '/path/to/audio.mp3',
    model: 'voxtral-small-latest'
);

Example — text-to-speech:

use HelgeSverre\Mistral\Dto\Audio\SpeechRequest;
use HelgeSverre\Mistral\Enums\SpeechOutputFormat;

$dto = $mistral->audio()->speechDto(
    SpeechRequest::withVoice(
        input: 'Hello from PHP!',
        voiceId: 'alice',
        responseFormat: SpeechOutputFormat::MP3,
    )
);

$dto->saveTo('hello.mp3');

Files Resource

Access via $mistral->files()

Methods:

• upload(string $filePath, ?FilePurpose $purpose): Response - Upload file
• uploadDto(...): UploadFileOut - Upload and return typed DTO
• list(...): Response - List files with filters
• listDto(...): ListFilesOut - List and return typed DTO
• retrieve(string $fileId): Response - Get file metadata
• retrieveDto(string $fileId): RetrieveFileOut - Get metadata and return typed DTO
• delete(string $fileId): Response - Delete file
• deleteDto(string $fileId): DeleteFileOut - Delete and return typed DTO
• download(string $fileId): Response - Download file content
• getSignedUrl(string $fileId, ?int $expiry): Response - Get signed download URL
• getSignedUrlDto(string $fileId, ?int $expiry): FileSignedURL - Get URL and return typed DTO

FineTuning Resource

Access via $mistral->fineTuning()

Methods:

• list(...): Response - List fine-tuning jobs
• listAsDto(...): JobsOut - List and return typed DTO
• create(JobIn $jobIn, ?bool $dryRun): Response - Create fine-tuning job
• createAsDto(JobIn $jobIn, ?bool $dryRun): CompletionJobOut|ClassifierJobOut|LegacyJobMetadataOut
• get(string $jobId): Response - Get job details
• getAsDto(string $jobId): CompletionDetailedJobOut|ClassifierDetailedJobOut
• cancel(string $jobId): Response - Cancel job
• cancelAsDto(string $jobId): CompletionDetailedJobOut|ClassifierDetailedJobOut
• start(string $jobId): Response - Start validated job
• startAsDto(string $jobId): CompletionDetailedJobOut|ClassifierDetailedJobOut
• updateModel(string $modelId, UpdateFTModelIn $update): Response - Update model metadata
• updateModelAsDto(...): CompletionFTModelOut|ClassifierFTModelOut
• archiveModel(string $modelId): Response - Archive model
• archiveModelAsDto(string $modelId): ArchiveFTModelOut
• unarchiveModel(string $modelId): Response - Unarchive model
• unarchiveModelAsDto(string $modelId): UnarchiveFTModelOut

Batch Resource

Access via $mistral->batch()

Methods:

• list(...): Response - List batch jobs
• listAsDto(...): BatchJobsOut - List and return typed DTO
• create(BatchJobIn $batchJobIn): Response - Create batch job
• createAsDto(BatchJobIn $batchJobIn): BatchJobOut - Create and return typed DTO
• get(string $jobId): Response - Get batch job details
• getAsDto(string $jobId): BatchJobOut - Get and return typed DTO
• cancel(string $jobId): Response - Cancel batch job
• cancelAsDto(string $jobId): BatchJobOut - Cancel and return typed DTO

Classifications Resource

Access via $mistral->classifications()

Methods:

• moderate(string $model, string|array $input): Response - Moderate content
• moderateAsDto(string $model, string|array $input): ModerationResponse - Moderate and return typed DTO
• moderateChat(string $model, array $input): Response - Moderate chat messages
• moderateChatAsDto(string $model, array $input): ModerationResponse - Moderate chat and return typed DTO
• classify(string $model, string|array $input): Response - Classify content
• classifyAsDto(string $model, string|array $input): ClassificationResponse - Classify and return typed DTO
• classifyChat(string $model, array $messages): Response - Classify chat
• classifyChatAsDto(string $model, array $messages): ClassificationResponse - Classify chat and return typed DTO

Example:

$moderation = $mistral->classifications()->moderateAsDto(
    model: 'mistral-moderation-latest',
    input: 'Text to moderate'
);

Libraries Resource

Access via $mistral->libraries()

Methods:

• list(?int $page, ?int $pageSize): Response - List libraries
• create(LibraryIn $library): Response - Create library
• get(string $libraryId): Response - Get library details
• update(string $libraryId, LibraryInUpdate $library): Response - Update library
• delete(string $libraryId): Response - Delete library
• listDocuments(string $libraryId, ...): Response - List documents in library
• uploadDocument(string $libraryId, string $filePath): Response - Upload document
• getDocument(string $libraryId, string $documentId): Response - Get document details
• updateDocument(string $libraryId, string $documentId, DocumentUpdateIn $update): Response - Update document
• deleteDocument(string $libraryId, string $documentId): Response - Delete document
• listSharing(string $libraryId): Response - List library sharing settings
• createSharing(string $libraryId, SharingIn $sharing): Response - Create/update sharing
• deleteSharing(string $libraryId, SharingDelete $sharing): Response - Delete sharing

Resources

Models Resource

List available models

// Get Response object
$response = $mistral->models()->list();

// Or get typed DTO directly
/** @var \HelgeSverre\Mistral\Dto\Models\ModelList $models */
$models = $mistral->models()->listDto();

Embeddings Resource

Create embedding

// Get Response object
$response = $mistral->embedding()->create([
    "A string here",
    "Another one here",
]);

// Or get typed DTO directly
/** @var EmbeddingResponse $embeddings */
$embeddings = $mistral->embedding()->createDto([
    "A string here",
    "Another one here",
]);

Chat Resource

Create Chat Completion

// Get Response object
$response = $mistral->chat()->create(
    messages: [
        [
            "role" => "user",
            "content" => "Write hello world in BASH",
        ]
    ],
    model: Model::medium->value,
    temperature: 0.4,
    maxTokens: 100,
    safeMode: false
);

// Or get typed DTO directly
/** @var ChatCompletionResponse $completion */
$completion = $mistral->chat()->createDto(
    messages: [
        [
            "role" => "user",
            "content" => "Write hello world in BASH",
        ]
    ],
    model: Model::medium->value,
    temperature: 0.4,
    maxTokens: 100,
    safeMode: false
);

Create Chat Completion with Function Calling

$response = $this->mistral->chat()->create(
    messages: [
        [
            'role' => Role::user->value,
            'content' => 'What is the weather in Bergen, Norway?',
        ],
    ],
    model: Model::large->value,
    maxTokens: 1000,
    tools: [
        [
            'type' => 'function',
            'function' => [
                'name' => 'searchWeather',
                'description' => 'Get the weather for a location',
                'parameters' => [
                    'type' => 'object',
                    'required' => [
                        'location',
                    ],
                    'properties' => [
                        'location' => [
                            'type' => 'string',
                            'description' => 'The location to get the weather for.',
                        ],
                    ],
                ],
            ],
        ],
        [
            'type' => 'function',
            'function' => [
                'name' => 'sendWeatherNotification',
                'description' => 'Send notification about weather to a user',
                'parameters' => [
                    'type' => 'object',
                    'required' => [
                        'userId',
                        'message',
                    ],
                    'properties' => [
                        'userId' => [
                            'type' => 'string',
                            'description' => 'the id of the user',
                        ],
                        'message' => [
                            'type' => 'string',
                            'description' => 'the message to send the user',
                        ],
                    ],
                ],
            ],
        ],
    ],
    toolChoice: 'any',
);

// Tool calls are returned in the response
$response->json('choices.0.message.tool_calls');
$response->json('choices.0.message.tool_calls.0.id');
$response->json('choices.0.message.tool_calls.0.type');
$response->json('choices.0.message.tool_calls.0.function');
$response->json('choices.0.message.tool_calls.0.function.name');
$response->json('choices.0.message.tool_calls.0.function.arguments');


// Or using the dto

/** @var ChatCompletionResponse $dto */
$dto = $response->dto();

$dto->choices; // array of ChatCompletionChoice

foreach ($dto->choices as $choice) {

    $choice->message; // ChatCompletionMessage

    foreach ($choice->message->toolCalls as $toolCall) {
        $toolCall->id; // null
        $toolCall->type; // function
        $toolCall->function; // FunctionCall
        $toolCall->function->name; // 'searchWeather'
        $toolCall->function->arguments; // '{"location":"Bergen, Norway"}'
        $toolCall->function->args(); // ['location' => 'Bergen, Norway']
    }
}

Create Streamed Chat Completions

// Returns a generator, which you can iterate over to get the streamed chunks
$stream = $mistral->chat()->createStreamed(
    messages: [
        [
            'role' => 'user',
            'content' => 'Make a markdown list of 10 common fruits'
        ],
    ],
    model: Model::small->value,
);

foreach ($stream as $chunk) {

    /** @var StreamedChatCompletionResponse $chunk */

    echo $chunk->id; // 'cmpl-0339459d35cb441b9f111b94216cff97'
    echo $chunk->model; // 'mistral-small'
    echo $chunk->object; // 'chat.completion.chunk'
    echo $chunk->created; // DateTime

    foreach ($chunk->choices as $choice) {
        $choice->index; // 0
        $choice->delta->role; // 'assistant'
        $choice->delta->content; // 'Fruit list...'
        $choice->finishReason; // 'length'
    }
}

SimpleChat Resource

For convenience, the client also provides a simple chat completion method, which returns a simpler, condensed and flattened DTO, which is useful for quick prototyping.

Create simple chat completions

$response = $mistral->simpleChat()->create(
    messages: [
        [
            "role" => "user",
            "content" => "Hello world!",
        ],
    ],
    model: Model::medium->value,
    temperature: 0.4,
    maxTokens: 1500,
    safeMode: false
);

/** @var SimpleChatResponse $response */

Create Streamed Simple Chat Completions

// Returns a generator, which you can iterate over to get the streamed chunks
$response = $mistral->simpleChat()->stream(
    messages: [
        [
            'role' => "user",
            'content' => 'Say the word "banana"',
        ],
    ],
    maxTokens: 100,
);

foreach ($response as $chunk) {
    /** @var SimpleStreamChunk $chunk */

    $chunk->id;           // 'cmpl-716e95d336db4e51a04cbcf2b84d1a76'
    $chunk->model;        // 'mistral-medium'
    $chunk->object;       // 'chat.completion.chunk'
    $chunk->created;      // '2024-01-03 12:00:00'
    $chunk->role;         // 'assistant'
    $chunk->content;      // 'the text \n'
    $chunk->finishReason; // 'length'
}

List of DTOs

For convenience, here is a list of all the DTOs available in this package, organized by feature area.

Chat

• Chat/ChatCompletionChoice.php
• Chat/ChatCompletionMessage.php
• Chat/ChatCompletionRequest.php
• Chat/ChatCompletionResponse.php
• Chat/StreamedChatCompletionChoice.php
• Chat/StreamedChatCompletionDelta.php
• Chat/StreamedChatCompletionResponse.php
• Chat/FunctionCall.php
• Chat/ToolCalls.php

SimpleChat

• SimpleChat/SimpleChatResponse.php
• SimpleChat/SimpleStreamChunk.php

Embeddings

• Embedding/EmbeddingRequest.php
• Embedding/EmbeddingResponse.php

Fill-in-the-Middle (FIM)

• Fim/FIMCompletionRequest.php
• Fim/FIMCompletionResponse.php
• Fim/FIMChoice.php
• Fim/StreamedFIMCompletionResponse.php
• Fim/StreamedFIMChoice.php
• Fim/StreamedFIMDelta.php

OCR

• OCR/OCRRequest.php
• OCR/OCRResponse.php
• OCR/Document.php
• OCR/Page.php
• OCR/Image.php
• OCR/Dimensions.php
• OCR/UsageInfo.php

Models

• Models/Model.php
• Models/ModelList.php
• Models/ModelPermission.php
• Models/ModelCapabilities.php
• Models/BaseModelCard.php
• Models/FTModelCard.php
• Models/DeleteModelOut.php

Fine-Tuning

• FineTuning/JobIn.php
• FineTuning/JobsOut.php
• FineTuning/JobMetadata.php
• FineTuning/LegacyJobMetadataOut.php
• FineTuning/CompletionJobOut.php
• FineTuning/ClassifierJobOut.php
• FineTuning/CompletionDetailedJobOut.php
• FineTuning/ClassifierDetailedJobOut.php
• FineTuning/CompletionFTModelOut.php
• FineTuning/ClassifierFTModelOut.php
• FineTuning/ArchiveFTModelOut.php
• FineTuning/UnarchiveFTModelOut.php
• FineTuning/UpdateFTModelIn.php
• FineTuning/TrainingFile.php
• FineTuning/TrainingParameters.php
• FineTuning/WandbIntegration.php
• FineTuning/Checkpoint.php
• FineTuning/CheckpointMetrics.php
• FineTuning/ValidationError.php

Files

• Files/FileObject.php
• Files/UploadFileOut.php
• Files/ListFilesOut.php
• Files/ListFilesRequest.php
• Files/RetrieveFileOut.php
• Files/DeleteFileOut.php
• Files/FileSignedURL.php

Batch

• Batch/BatchJobIn.php
• Batch/BatchJobOut.php
• Batch/BatchJobsOut.php

Audio

• Audio/TranscriptionResponse.php
• Audio/TranscriptionSegment.php
• Audio/TranscriptionWord.php
• Audio/SpeechRequest.php
• Audio/SpeechResponse.php
• Audio/SpeechStreamAudioDelta.php
• Audio/SpeechStreamDone.php
• Audio/VoiceResponse.php
• Audio/VoiceListResponse.php
• Audio/VoiceCreateRequest.php
• Audio/VoiceUpdateRequest.php

Classifications & Moderation

• Classifications/ClassificationRequest.php
• Classifications/ChatClassificationRequest.php
• Classifications/ClassificationResponse.php
• Classifications/ClassificationResult.php
• Moderations/ChatModerationRequest.php
• Moderations/ModerationResponse.php
• Moderations/ModerationResult.php
• Moderations/ModerationCategories.php
• Moderations/ModerationCategoryScores.php

Agents

• Agents/Agent.php
• Agents/AgentList.php
• Agents/AgentCreationRequest.php
• Agents/AgentUpdateRequest.php
• Agents/AgentAliasResponse.php

Conversations

• Conversations/ConversationRequest.php
• Conversations/ConversationAppendRequest.php
• Conversations/ConversationRestartRequest.php
• Conversations/ConversationResponse.php
• Conversations/ConversationList.php
• Conversations/ConversationHistory.php
• Conversations/ConversationMessages.php
• Conversations/ConversationEntry.php
• Conversations/ConversationMessage.php
• Conversations/ModelConversation.php
• Conversations/AgentConversation.php

Libraries

• Libraries/LibraryIn.php
• Libraries/LibraryInUpdate.php
• Libraries/LibraryOut.php
• Libraries/ListLibraryOut.php
• Libraries/DocumentOut.php
• Libraries/DocumentUpdateIn.php
• Libraries/ListDocumentOut.php
• Libraries/SharingIn.php
• Libraries/SharingDelete.php
• Libraries/SharingOut.php
• Libraries/ListSharingOut.php

Shared/Common

• Usage.php

List of available Mistral models

The following models are available in the Mistral API. You can use the Model enum in this package to refer to them, or use the string value directly.

Current Production Models

Open Source Models

For the most up-to-date model information and capabilities, visit the Mistral AI Models Documentation.

Testing

cp .env.example .env
composer test
composer analyse src

License

The MIT License (MIT). Please see License File for more information.

Disclaimer

Mistral and the Mistral logo are trademarks of Mistral.ai. This package is not affiliated with, endorsed by, or sponsored by Mistral.ai. All trademarks and registered trademarks are the property of their respective owners.

See Mistral.AI for more information.