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', 'https://api.mistral.ai'),
    'timeout' => env('MISTRAL_TIMEOUT', 30),
];

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 10 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.

Example	Description
01-getting-started	Install the SDK, configure authentication, and make your first API call
02-basic-chat	Learn chat completions, system messages, and multi-turn conversations
03-chat-parameters	Master temperature, top_p, max_tokens, and other generation parameters
04-streaming-chat	Implement real-time streaming responses with Server-Sent Events
05-function-calling	Enable AI to call PHP functions and interact with your application
06-embeddings	Generate vector embeddings for semantic search and similarity matching
07-ocr	Extract and process text from images and documents using OCR
08-audio	Transcribe audio files with support for multiple languages and formats
09-moderation	Identify and filter inappropriate content with content moderation
10-error-handling	Implement robust error handling, retry logic, and rate limit management

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, each offering both Response-returning methods and typed DTO methods for convenient type-safe usage.

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

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:

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

Example:

$transcription = $mistral->audio()->transcribeDto(
    filePath: '/path/to/audio.mp3',
    model: 'whisper-large-v3'
);

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 = $this->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 ChatCompletionResponse $response */

`SimpleChat` Resource

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

Create Streamed Simple Chat Completions

// Returns a generator, which you can iterate over to get the streamed chunks
$response = $this->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

SimpleChat

Embeddings

Fill-in-the-Middle (FIM)

OCR

Models

Fine-Tuning

Files

Batch

Audio

Classifications & Moderation

Agents

Conversations

Libraries

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

Enum Case	String Value	Type	Description
`Model::large->value`	`'mistral-large-latest'`	Chat	Most capable model for complex reasoning and specialized tasks
`Model::medium->value`	`'mistral-medium-latest'`	Chat	Balanced model for intermediate tasks (alias: mistral-medium-2508)
`Model::small->value`	`'mistral-small-latest'`	Chat	Fast, efficient model for simple bulk tasks (alias: mistral-small-2506)
`Model::pixtralLarge->value`	`'pixtral-large-latest'`	Vision	Advanced vision model for image understanding
`Model::pixtral12b->value`	`'pixtral-12b-latest'`	Vision	Efficient vision model
`Model::codestral->value`	`'codestral-latest'`	Code	Specialized model for code generation and understanding
`Model::ministral8b->value`	`'ministral-8b-latest'`	Chat	Compact 8B parameter model
`Model::ministral3b->value`	`'ministral-3b-latest'`	Chat	Ultra-compact 3B parameter model for edge deployment
`Model::embed->value`	`'mistral-embed'`	Embeddings	Text embedding model for semantic search and retrieval

Open Source Models

Enum Case	String Value	Type	Description
`Model::mistral7b->value`	`'open-mistral-7b'`	Chat	7B parameter open source foundation model
`Model::mixtral->value`	`'open-mixtral-8x7b'`	Chat	Mixture of Experts model with 8x7B parameters

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.

helgesverre / mistral

Maintainers

Details

README

Laravel Client for Mistral.AI

Installation

Usage

Client Instantiation

Examples

Available Resources & Methods

Chat Resource

SimpleChat Resource

Embedding Resource

Models Resource

OCR Resource

FIM Resource (Fill-in-the-Middle)

Agents Resource

Conversations Resource

Audio Resource

Files Resource

FineTuning Resource

Batch Resource

Classifications Resource

Libraries Resource

Resources

Models Resource

List available models

Embeddings Resource

Create embedding

Chat Resource

Create Chat Completion

Create Chat Completion with Function Calling

Create Streamed Chat Completions

SimpleChat Resource

Create simple chat completions

SimpleChat Resource

Create Streamed Simple Chat Completions

List of DTOs

Chat

SimpleChat

Embeddings

Fill-in-the-Middle (FIM)

OCR

Models

Fine-Tuning

Files

Batch

Audio

Classifications & Moderation

Agents

Conversations

Libraries

Shared/Common

List of available Mistral models

Current Production Models

Open Source Models

Testing

License

Disclaimer

`Models` Resource

`Embeddings` Resource

`Chat` Resource

`SimpleChat` Resource

`SimpleChat` Resource