README

A lightweight, underrated PSR-17/PSR-18 client for the current Mistral AI API, with examples for every exposed SDK method, SSE streaming, streamed multipart uploads, and structured errors.

Requirements

• PHP 8.1 or newer. CI tests PHP 8.1, 8.2, 8.3, 8.4, and 8.5.
• A PSR-17 request, stream, and URI factory.
• A PSR-18 HTTP client.
• The JSON extension.

Guzzle is used below because it provides both the PSR-17 factories and a PSR-18 client implementation. The SDK itself depends only on the PSR interfaces, so other compliant implementations remain supported.

Installation

composer require softcreatr/php-mistral-ai-sdk guzzlehttp/guzzle

Client Setup

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use SoftCreatR\MistralAI\MistralAI;

$factory = new HttpFactory();
$mistral = new MistralAI(
    requestFactory: $factory,
    streamFactory: $factory,
    uriFactory: $factory,
    httpClient: new Client(['stream' => true]),
    apiKey: (string) getenv('MISTRAL_API_KEY'),
);

Keep API keys on the server and out of source control.

Chat Completions

use const JSON_THROW_ON_ERROR;

$response = $mistral->createChatCompletion([
    'model' => 'mistral-small-latest',
    'messages' => [
        ['role' => 'user', 'content' => 'Give me a one-sentence summary of PSR-18.'],
    ],
]);

$result = json_decode((string) $response->getBody(), true, 512, JSON_THROW_ON_ERROR);
echo $result['choices'][0]['message']['content'];

Endpoint methods return a PSR-7 ResponseInterface, including calls that deliver SSE events to a callback.

Arguments

Body-only endpoints use a single body array:

$mistral->createEmbedding([
    'model' => 'mistral-embed',
    'input' => 'A sentence to embed.',
]);

For endpoints with path parameters, a single combined array is the preferred v4 form. Path fields are separated from the request body using the endpoint template:

$mistral->updateAgent([
    'agent_id' => 'ag_abc123',
    'description' => 'Updated description',
]);

The v3 two-array form remains supported for existing integrations:

$mistral->updateAgent(
    ['agent_id' => 'ag_abc123'],
    ['description' => 'Updated description'],
);

For GET and DELETE methods, non-path values become RFC 3986 query parameters. Path parameter values are URL encoded. The explicit form is available when method names are determined at runtime:

$response = $mistral->request(
    'listFiles',
    ['page' => 0, 'page_size' => 20],
    customHeaders: ['X-Trace-Id' => 'trace_abc123'],
);

Streaming

Set stream to true and pass a callback. The decoder supports arbitrarily split chunks, CRLF and LF delimiters, comments, multiline data fields, final unterminated frames, and [DONE].

$mistral->createChatCompletion(
    [
        'model' => 'mistral-small-latest',
        'messages' => [['role' => 'user', 'content' => 'Write a short haiku about PHP.']],
        'stream' => true,
    ],
    static function (array $event): void {
        echo $event['choices'][0]['delta']['content'] ?? '';
    },
);

An ordinary JSON response is still returned when a callback is supplied without requesting an SSE stream. Inherently streaming endpoints select a StreamingClientInterface transport without requiring a body flag.

File Uploads

Multipart endpoints accept readable local file paths. Files are copied as raw bytes into a temporary stream rather than being base64 encoded or assembled in one large PHP string.

$response = $mistral->uploadFile([
    'file' => __DIR__ . '/batch.jsonl',
    'purpose' => 'batch',
]);

Nested non-file values are encoded using bracket notation.

Errors

4xx and 5xx responses throw MistralAIException. The exception keeps the parsed API error, raw response body, response headers, status code, and x-request-id for diagnostics.

use SoftCreatR\MistralAI\Exception\MistralAIException;

try {
    $mistral->retrieveModel(['model_id' => 'missing-model']);
} catch (MistralAIException $exception) {
    error_log(sprintf(
        'Mistral AI request %s failed (%d): %s',
        $exception->getRequestId() ?? 'unknown',
        $exception->getCode(),
        $exception->getMessage(),
    ));
}

PSR-18 transport failures are wrapped in MistralAIException and retain the original exception as getPrevious().

Examples

Examples load the ignored project-level .env through examples/MistralAIFactory.php:

cp .env.example .env
php examples/chat/createChatCompletion.php

Administration examples use MISTRAL_ADMIN_API_KEY. Resource-specific examples read IDs from the variables documented in .env.example.

Supported Methods

The catalog follows the current Mistral AI API reference. Beta endpoints remain grouped by their documented API area, and the v2 Prompts and Skills routes use their endpoint-specific base path automatically.

Prompts

Skills

Audio

Models

Conversations

Agents

Files

Batch

Chat

Fim

Embeddings

Classifiers

Ocr

Libraries

Libraries / Documents

Libraries / Shares

Observability / Chat Completion Events

Observability / Chat Completion Events / Fields

Observability / Judges

Observability / Campaigns

Observability / Datasets

Observability / Datasets / Records

Observability / Logs

Observability / Traces

Observability / Spans

Connectors

Workflows / Executions

Workflows / Metrics

Workflows / Runs

Workflows / Schedules

Workflows / Events

Workflows / Deployments

Workflows

Rag / Ingestion

Rag / Search Indexes

Users

Administration / Users

Administration / Workspaces

Administration / Billing

Administration / Audit Logs

Administration / User Groups

Administration / Api Keys

Administration / Scim

Administration / Vibe Work Analytics

Administration / Vibe Code Analytics

Changelog

See CHANGELOG.md for release history and migration notes.

License

This library is licensed under the ISC License. See LICENSE.md.