0
# Mistral AI Python SDK
1

2
A comprehensive Python client SDK for interacting with the Mistral AI API. Provides access to chat completions, embeddings, fine-tuning, agents, file management, and advanced AI capabilities with both synchronous and asynchronous support.
3

4
## Package Information
5

6
- **Package Name**: mistralai
7
- **Language**: Python
8
- **Installation**: `pip install mistralai`
9
- **Documentation**: https://docs.mistral.ai
10

11
## Core Imports
12

13
```python
14
from mistralai import Mistral
15
```
16

17
For specific components:
18

19
```python
20
from mistralai.models import (
21
    ChatCompletionRequest,
22
    ChatCompletionResponse,
23
    SystemMessage,
24
    UserMessage,
25
    AssistantMessage
26
)
27
```
28

29
## Basic Usage
30

31
```python
32
from mistralai import Mistral
33
from mistralai.models import UserMessage
34

35
# Initialize client
36
client = Mistral(api_key="your-api-key")
37

38
# Simple chat completion
39
messages = [
40
    UserMessage(content="Hello, how are you?")
41
]
42

43
response = client.chat.complete(
44
    model="mistral-small-latest",
45
    messages=messages
46
)
47

48
print(response.choices[0].message.content)
49

50
# Async usage
51
async with Mistral(api_key="your-api-key") as client:
52
    response = await client.chat.complete(
53
        model="mistral-small-latest", 
54
        messages=messages
55
    )
56
    print(response.choices[0].message.content)
57
```
58

59
## Architecture
60

61
The SDK is built around a main `Mistral` class that provides access to specialized sub-APIs:
62

63
- **Main SDK**: Central client with authentication, configuration, and sub-API access
64
- **Sub-APIs**: Focused modules for specific functionality (chat, agents, embeddings, etc.)
65
- **Models**: Comprehensive type system for requests, responses, and data structures
66
- **Utilities**: Serialization, HTTP handling, streaming, and retry logic
67
- **Context Management**: Automatic resource cleanup and connection management
68

69
The design enables both simple usage patterns and advanced customization while maintaining type safety and comprehensive error handling.
70

71
## Capabilities
72

73
### Chat Completions
74

75
Create text completions using Mistral's language models with support for conversations, function calling, streaming responses, and structured outputs.
76

77
```python { .api }
78
def complete(
79
    model: str,
80
    messages: List[Union[SystemMessage, UserMessage, AssistantMessage, ToolMessage]],
81
    temperature: Optional[float] = None,
82
    top_p: Optional[float] = None,
83
    max_tokens: Optional[int] = None,
84
    stream: Optional[bool] = None,
85
    tools: Optional[List[Tool]] = None,
86
    tool_choice: Optional[Union[str, ToolChoice]] = None,
87
    response_format: Optional[ResponseFormat] = None,
88
    **kwargs
89
) -> ChatCompletionResponse: ...
90

91
def stream(
92
    model: str,
93
    messages: List[Union[SystemMessage, UserMessage, AssistantMessage, ToolMessage]],
94
    **kwargs
95
) -> Iterator[CompletionChunk]: ...
96
```
97

98
[Chat Completions](./chat-completions.md)
99

100
### Agents
101

102
Generate completions using pre-configured AI agents with specialized tools and context.
103

104
```python { .api }
105
def complete(
106
    messages: List[Union[SystemMessage, UserMessage, AssistantMessage, ToolMessage]],
107
    agent_id: str,
108
    max_tokens: Optional[int] = None,
109
    stream: Optional[bool] = False,
110
    tools: Optional[List[Tool]] = None,
111
    tool_choice: Optional[Union[str, ToolChoice]] = None,
112
    **kwargs
113
) -> ChatCompletionResponse: ...
114

115
def stream(
116
    messages: List[Union[SystemMessage, UserMessage, AssistantMessage, ToolMessage]],
117
    agent_id: str,
118
    max_tokens: Optional[int] = None,
119
    stream: Optional[bool] = True,
120
    **kwargs
121
) -> Iterator[CompletionEvent]: ...
122
```
123

124
[Agents](./agents.md)
125

126
### Embeddings
127

128
Generate vector embeddings for text input with support for different models and output formats.
129

130
```python { .api }
131
def create(
132
    model: str,
133
    inputs: Union[str, List[str]],
134
    output_dimension: Optional[int] = None,
135
    output_dtype: Optional[str] = None,
136
    encoding_format: Optional[str] = None,
137
    **kwargs
138
) -> EmbeddingResponse: ...
139
```
140

141
[Embeddings](./embeddings.md)
142

143
### Models
144

145
List and manage available models including base models and fine-tuned models.
146

147
```python { .api }
148
def list(**kwargs) -> ModelList: ...
149

150
def retrieve(model_id: str, **kwargs) -> Union[BaseModelCard, FTModelCard]: ...
151

152
def delete(model_id: str, **kwargs) -> DeleteModelOut: ...
153
```
154

155
[Models](./models.md)
156

157
### Files
158

159
Upload, manage, and process files for use with fine-tuning, agents, and other AI capabilities.
160

161
```python { .api }
162
def upload(
163
    file: Union[File, FileTypedDict],
164
    purpose: Optional[FilePurpose] = None,
165
    **kwargs
166
) -> UploadFileOut: ...
167

168
def list(
169
    page: Optional[int] = 0,
170
    page_size: Optional[int] = 100,
171
    sample_type: Optional[List[SampleType]] = None,
172
    source: Optional[List[Source]] = None,
173
    search: Optional[str] = None,
174
    purpose: Optional[FilePurpose] = None,
175
    **kwargs
176
) -> ListFilesOut: ...
177

178
def retrieve(file_id: str, **kwargs) -> RetrieveFileOut: ...
179

180
def delete(file_id: str, **kwargs) -> DeleteFileOut: ...
181

182
def download(file_id: str, **kwargs) -> httpx.Response: ...
183

184
def get_signed_url(
185
    file_id: str,
186
    expiry: Optional[int] = 24,
187
    **kwargs
188
) -> FileSignedURL: ...
189
```
190

191
[Files](./files.md)
192

193
### Fine-tuning
194

195
Create and manage fine-tuning jobs to customize models for specific use cases.
196

197
```python { .api }
198
def create(
199
    model: str,
200
    training_files: List[TrainingFile],
201
    validation_files: Optional[List[TrainingFile]] = None,
202
    hyperparameters: Optional[dict] = None,
203
    **kwargs
204
) -> CompletionDetailedJobOut: ...
205

206
def list(**kwargs) -> JobsOut: ...
207

208
def get(job_id: str, **kwargs) -> CompletionDetailedJobOut: ...
209

210
def cancel(job_id: str, **kwargs) -> CompletionDetailedJobOut: ...
211
```
212

213
[Fine-tuning](./fine-tuning.md)
214

215
### Batch Processing
216

217
Submit and manage batch processing jobs for handling large volumes of requests efficiently.
218

219
```python { .api }
220
def create(
221
    input_files: List[str],
222
    endpoint: str,
223
    completion_window: str,
224
    **kwargs
225
) -> BatchJobOut: ...
226

227
def list(**kwargs) -> BatchJobsOut: ...
228

229
def get(batch_id: str, **kwargs) -> BatchJobOut: ...
230

231
def cancel(batch_id: str, **kwargs) -> BatchJobOut: ...
232
```
233

234
[Batch Processing](./batch.md)
235

236
### Fill-in-the-Middle (FIM)
237

238
Generate code completions using fill-in-the-middle models for code editing and completion tasks.
239

240
```python { .api }
241
def complete(
242
    model: str,
243
    prompt: str,
244
    suffix: Optional[str] = None,
245
    temperature: Optional[float] = None,
246
    max_tokens: Optional[int] = None,
247
    **kwargs
248
) -> FIMCompletionResponse: ...
249
```
250

251
[Fill-in-the-Middle](./fim.md)
252

253
### OCR
254

255
Process documents and images to extract text and structured data using optical character recognition.
256

257
```python { .api }
258
def process(
259
    model: str,
260
    document: Document,
261
    pages: Optional[List[int]] = None,
262
    **kwargs
263
) -> OCRResponse: ...
264
```
265

266
[OCR](./ocr.md)
267

268
### Content Classification
269

270
Moderate content and classify text using Mistral's safety and classification models.
271

272
```python { .api }
273
def moderate(
274
    inputs: List[Union[str, Dict]],
275
    model: Optional[str] = None,
276
    **kwargs
277
) -> ModerationResponse: ...
278

279
def classify(
280
    inputs: List[str],
281
    model: str,
282
    **kwargs
283
) -> ClassificationResponse: ...
284
```
285

286
[Classification](./classification.md)
287

288
### Audio Transcription
289

290
Transcribe audio files to text with support for various audio formats and streaming.
291

292
```python { .api }
293
def transcribe(
294
    file: Union[str, BinaryIO],
295
    model: str,
296
    language: Optional[str] = None,
297
    **kwargs
298
) -> TranscriptionResponse: ...
299

300
def transcribe_stream(
301
    stream: Iterator[bytes],
302
    model: str,
303
    **kwargs
304
) -> Iterator[TranscriptionStreamEvents]: ...
305
```
306

307
[Audio](./audio.md)
308

309
### Beta APIs
310

311
Experimental and preview APIs providing access to advanced features including enhanced conversations, document libraries, and beta agent capabilities.
312

313
```python { .api }
314
# Conversations API
315
def start(
316
    inputs: Union[ConversationInputs, dict],
317
    instructions: Optional[str] = None,
318
    tools: Optional[List[Tool]] = None,
319
    **kwargs
320
) -> ConversationResponse: ...
321

322
def start_stream(
323
    inputs: Union[ConversationInputs, dict],
324
    **kwargs
325
) -> Iterator[ConversationEvents]: ...
326

327
# Libraries API  
328
def create(
329
    name: str,
330
    description: Optional[str] = None,
331
    **kwargs
332
) -> LibraryOut: ...
333

334
def list(**kwargs) -> ListLibraryOut: ...
335

336
# Beta Agents API (enhanced agent management)
337
def create(
338
    name: str,
339
    model: str,
340
    **kwargs
341
) -> Agent: ...
342

343
def update_version(
344
    agent_id: str,
345
    version_data: dict,
346
    **kwargs
347
) -> Agent: ...
348
```
349

350
[Beta APIs](./beta.md)
351

352
## Core Types
353

354
### Main SDK Class
355

356
```python { .api }
357
class Mistral:
358
    def __init__(
359
        self,
360
        api_key: Optional[Union[str, Callable[[], str]]] = None,
361
        server_url: Optional[str] = None,
362
        client: Optional[HttpClient] = None,
363
        async_client: Optional[AsyncHttpClient] = None,
364
        retry_config: Optional[RetryConfig] = None,
365
        timeout_ms: Optional[int] = None,
366
        debug_logger: Optional[Logger] = None,
367
    ) -> None: ...
368
    
369
    def __enter__(self) -> "Mistral": ...
370
    def __exit__(self, exc_type, exc_val, exc_tb) -> None: ...
371
    async def __aenter__(self) -> "Mistral": ...
372
    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None: ...
373
```
374

375
### Message Types
376

377
```python { .api }
378
class SystemMessage:
379
    content: Union[str, List[SystemMessageContentChunk]]
380
    role: Optional[Literal["system"]] = "system"
381

382
class UserMessage:
383
    content: Optional[Union[str, List[ContentChunk]]]
384
    role: Optional[Literal["user"]] = "user"
385

386
class AssistantMessage:
387
    content: Optional[Union[str, List[ContentChunk]]]
388
    tool_calls: Optional[List[ToolCall]]
389
    prefix: Optional[bool] = False
390
    role: Optional[Literal["assistant"]] = "assistant"
391

392
class ToolMessage:
393
    content: Optional[Union[str, List[ContentChunk]]]
394
    tool_call_id: Optional[str]
395
    name: Optional[str]
396
    role: Optional[Literal["tool"]] = "tool"
397

398
# Content chunk types for multimodal support
399
ContentChunk = Union[
400
    TextChunk,
401
    ImageURLChunk,
402
    DocumentURLChunk,
403
    FileChunk,
404
    AudioChunk,
405
    ReferenceChunk,
406
    ThinkChunk
407
]
408

409
class TextChunk:
410
    type: Literal["text"]
411
    text: str
412

413
class ImageURLChunk:
414
    type: Literal["image_url"]
415
    image_url: str
416

417
class DocumentURLChunk:
418
    type: Literal["document_url"]
419
    document_url: str
420

421
class FileChunk:
422
    type: Literal["file"]
423
    file: str
424

425
class AudioChunk:
426
    type: Literal["input_audio"]
427
    input_audio: dict
428

429
class ReferenceChunk:
430
    type: Literal["reference"]
431
    reference: str
432

433
class ThinkChunk:
434
    type: Literal["thinking"]
435
    thinking: str
436
```
437

438
### Tool Types
439

440
```python { .api }
441
class FunctionTool:
442
    type: Literal["function"]
443
    function: Function
444

445
class CodeInterpreterTool:
446
    type: Literal["code_interpreter"]
447

448
class WebSearchTool:
449
    type: Literal["web_search"]
450

451
class WebSearchPremiumTool:
452
    type: Literal["web_search_premium"]
453

454
class DocumentLibraryTool:
455
    type: Literal["document_library"]
456
    document_library: dict
457

458
class ImageGenerationTool:
459
    type: Literal["image_generation"]
460
```
461

462
### Configuration Types
463

464
```python { .api }
465
class ResponseFormat:
466
    type: Literal["json_object", "text"]
467
    schema: Optional[dict]
468

469
class ToolChoice:
470
    type: Literal["auto", "none", "any"]
471
    function: Optional[FunctionName]
472

473
class RetryConfig:
474
    strategy: str
475
    backoff: dict
476
    retries: int
477
```
478

479
### Response Types
480

481
```python { .api }
482
class ChatCompletionResponse:
483
    id: str
484
    object: str
485
    created: int
486
    model: str
487
    choices: List[ChatCompletionChoice]
488
    usage: Optional[UsageInfo]
489

490
class EmbeddingResponse:
491
    id: str
492
    object: str
493
    data: List[EmbeddingResponseData]
494
    model: str
495
    usage: Optional[UsageInfo]
496

497
class UsageInfo:
498
    prompt_tokens: int
499
    completion_tokens: Optional[int]
500
    total_tokens: int
501
```