0
# Chat Completions
1

2
Create text completions using Mistral's language models with support for conversations, function calling, streaming responses, and structured outputs. The chat completions API is the core interface for generating AI responses.
3

4
## Capabilities
5

6
### Basic Chat Completion
7

8
Generate responses for conversational AI applications with support for system prompts, user messages, and assistant responses.
9

10
```python { .api }
11
def complete(
12
    model: str,
13
    messages: List[Union[SystemMessage, UserMessage, AssistantMessage, ToolMessage]],
14
    temperature: Optional[float] = None,
15
    top_p: Optional[float] = None,
16
    max_tokens: Optional[int] = None,
17
    stream: Optional[bool] = None,
18
    stop: Optional[Union[str, List[str]]] = None,
19
    random_seed: Optional[int] = None,
20
    response_format: Optional[ResponseFormat] = None,
21
    tools: Optional[List[Tool]] = None,
22
    tool_choice: Optional[Union[str, ToolChoice]] = None,
23
    safe_prompt: Optional[bool] = None,
24
    **kwargs
25
) -> ChatCompletionResponse:
26
    """
27
    Create a chat completion.
28

29
    Parameters:
30
    - model: Model identifier (e.g., "mistral-small-latest", "mistral-large-latest")
31
    - messages: List of conversation messages
32
    - temperature: Sampling temperature (0.0 to 1.0)
33
    - top_p: Nucleus sampling parameter (0.0 to 1.0)
34
    - max_tokens: Maximum tokens to generate
35
    - stream: Enable streaming responses
36
    - stop: Stop sequences for generation
37
    - random_seed: Seed for reproducible outputs
38
    - response_format: Format specification for structured outputs
39
    - tools: Available tools for function calling
40
    - tool_choice: Tool selection strategy
41
    - safe_prompt: Enable prompt safety checking
42

43
    Returns:
44
    ChatCompletionResponse with generated content
45
    """
46
```
47

48
### Streaming Chat Completion
49

50
Stream responses in real-time for better user experience with long-form content generation.
51

52
```python { .api }
53
def stream(
54
    model: str,
55
    messages: List[Union[SystemMessage, UserMessage, AssistantMessage, ToolMessage]],
56
    temperature: Optional[float] = None,
57
    top_p: Optional[float] = None,
58
    max_tokens: Optional[int] = None,
59
    stop: Optional[Union[str, List[str]]] = None,
60
    random_seed: Optional[int] = None,
61
    tools: Optional[List[Tool]] = None,
62
    tool_choice: Optional[Union[str, ToolChoice]] = None,
63
    **kwargs
64
) -> Iterator[CompletionChunk]:
65
    """
66
    Create a streaming chat completion.
67

68
    Parameters:
69
    - model: Model identifier
70
    - messages: List of conversation messages
71
    - temperature: Sampling temperature (0.0 to 1.0)
72
    - top_p: Nucleus sampling parameter (0.0 to 1.0)
73
    - max_tokens: Maximum tokens to generate
74
    - stop: Stop sequences for generation
75
    - random_seed: Seed for reproducible outputs
76
    - tools: Available tools for function calling
77
    - tool_choice: Tool selection strategy
78

79
    Returns:
80
    Iterator of CompletionChunk objects with streaming content
81
    """
82
```
83

84
### Structured Output Parsing
85

86
Parse responses into structured formats using Pydantic models for type-safe data extraction.
87

88
```python { .api }
89
def parse(
90
    model: str,
91
    messages: List[Union[SystemMessage, UserMessage, AssistantMessage, ToolMessage]],
92
    response_model: Type[BaseModel],
93
    temperature: Optional[float] = None,
94
    max_tokens: Optional[int] = None,
95
    **kwargs
96
) -> BaseModel:
97
    """
98
    Parse chat completion into structured format.
99

100
    Parameters:
101
    - model: Model identifier
102
    - messages: List of conversation messages
103
    - response_model: Pydantic model class for parsing
104
    - temperature: Sampling temperature
105
    - max_tokens: Maximum tokens to generate
106

107
    Returns:
108
    Parsed model instance with structured data
109
    """
110

111
async def parse_async(
112
    model: str,
113
    messages: List[Union[SystemMessage, UserMessage, AssistantMessage, ToolMessage]],
114
    response_model: Type[BaseModel],
115
    **kwargs
116
) -> BaseModel:
117
    """
118
    Async version of parse method.
119
    """
120

121
def parse_stream(
122
    model: str,
123
    messages: List[Union[SystemMessage, UserMessage, AssistantMessage, ToolMessage]],
124
    response_model: Type[BaseModel],
125
    **kwargs
126
) -> Iterator[BaseModel]:
127
    """
128
    Stream parsed structured outputs.
129
    """
130

131
async def parse_stream_async(
132
    model: str,
133
    messages: List[Union[SystemMessage, UserMessage, AssistantMessage, ToolMessage]],
134
    response_model: Type[BaseModel],
135
    **kwargs
136
) -> AsyncIterator[BaseModel]:
137
    """
138
    Async stream parsed structured outputs.
139
    """
140
```
141

142
## Usage Examples
143

144
### Basic Conversation
145

146
```python
147
from mistralai import Mistral
148
from mistralai.models import SystemMessage, UserMessage
149

150
client = Mistral(api_key="your-api-key")
151

152
messages = [
153
    SystemMessage(content="You are a helpful assistant."),
154
    UserMessage(content="Explain quantum computing in simple terms.")
155
]
156

157
response = client.chat.complete(
158
    model="mistral-small-latest",
159
    messages=messages,
160
    temperature=0.7,
161
    max_tokens=500
162
)
163

164
print(response.choices[0].message.content)
165
```
166

167
### Function Calling
168

169
```python
170
from mistralai.models import FunctionTool, Function
171

172
# Define a tool
173
weather_tool = FunctionTool(
174
    type="function",
175
    function=Function(
176
        name="get_weather",
177
        description="Get current weather for a location",
178
        parameters={
179
            "type": "object",
180
            "properties": {
181
                "location": {"type": "string", "description": "City name"},
182
                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
183
            },
184
            "required": ["location"]
185
        }
186
    )
187
)
188

189
messages = [
190
    UserMessage(content="What's the weather like in Paris?")
191
]
192

193
response = client.chat.complete(
194
    model="mistral-small-latest",
195
    messages=messages,
196
    tools=[weather_tool],
197
    tool_choice="auto"
198
)
199

200
# Handle tool calls in response
201
if response.choices[0].message.tool_calls:
202
    for tool_call in response.choices[0].message.tool_calls:
203
        print(f"Tool: {tool_call.function.name}")
204
        print(f"Arguments: {tool_call.function.arguments}")
205
```
206

207
### Streaming Response
208

209
```python
210
messages = [
211
    UserMessage(content="Write a short story about a robot.")
212
]
213

214
stream = client.chat.stream(
215
    model="mistral-small-latest",
216
    messages=messages,
217
    temperature=0.8
218
)
219

220
for chunk in stream:
221
    if chunk.choices[0].delta.content:
222
        print(chunk.choices[0].delta.content, end="", flush=True)
223
```
224

225
### Structured Output
226

227
```python
228
from pydantic import BaseModel
229
from typing import List
230

231
class Recipe(BaseModel):
232
    name: str
233
    ingredients: List[str]
234
    instructions: List[str]
235
    prep_time_minutes: int
236

237
messages = [
238
    UserMessage(content="Give me a recipe for chocolate chip cookies.")
239
]
240

241
recipe = client.chat.parse(
242
    model="mistral-small-latest",
243
    messages=messages,
244
    response_model=Recipe
245
)
246

247
print(f"Recipe: {recipe.name}")
248
print(f"Prep time: {recipe.prep_time_minutes} minutes")
249
print(f"Ingredients: {', '.join(recipe.ingredients)}")
250
```
251

252
## Types
253

254
### Request Types
255

256
```python { .api }
257
class ChatCompletionRequest:
258
    model: str
259
    messages: List[Union[SystemMessage, UserMessage, AssistantMessage, ToolMessage]]
260
    temperature: Optional[float]
261
    top_p: Optional[float]
262
    max_tokens: Optional[int]
263
    stream: Optional[bool]
264
    stop: Optional[Union[str, List[str]]]
265
    random_seed: Optional[int]
266
    response_format: Optional[ResponseFormat]
267
    tools: Optional[List[Tool]]
268
    tool_choice: Optional[Union[str, ToolChoice]]
269
    safe_prompt: Optional[bool]
270

271
class ChatCompletionStreamRequest:
272
    model: str
273
    messages: List[Union[SystemMessage, UserMessage, AssistantMessage, ToolMessage]]
274
    temperature: Optional[float]
275
    top_p: Optional[float]
276
    max_tokens: Optional[int]
277
    stop: Optional[Union[str, List[str]]]
278
    random_seed: Optional[int]
279
    tools: Optional[List[Tool]]
280
    tool_choice: Optional[Union[str, ToolChoice]]
281
```
282

283
### Response Types
284

285
```python { .api }
286
class ChatCompletionResponse:
287
    id: str
288
    object: str
289
    created: int
290
    model: str
291
    choices: List[ChatCompletionChoice]
292
    usage: Optional[UsageInfo]
293

294
class ChatCompletionChoice:
295
    index: int
296
    message: AssistantMessage
297
    finish_reason: Optional[str]  # "stop", "length", "tool_calls", "content_filter"
298

299
class CompletionChunk:
300
    id: str
301
    object: str
302
    created: int
303
    model: str
304
    choices: List[CompletionResponseStreamChoice]
305

306
class CompletionResponseStreamChoice:
307
    index: int
308
    delta: DeltaMessage
309
    finish_reason: Optional[str]
310

311
class DeltaMessage:
312
    role: Optional[str]
313
    content: Optional[str]
314
    tool_calls: Optional[List[ToolCall]]
315
```
316

317
### Content Types
318

319
```python { .api }
320
class TextChunk:
321
    type: Literal["text"]
322
    text: str
323

324
class ImageURLChunk:
325
    type: Literal["image_url"]
326
    image_url: ImageURL
327

328
class ImageURL:
329
    url: str
330
    detail: Optional[str]  # "auto", "low", "high"
331
```
332

333
### Tool Types
334

335
```python { .api }
336
class ToolCall:
337
    id: str
338
    type: str
339
    function: FunctionCall
340

341
class FunctionCall:
342
    name: str
343
    arguments: str
344

345
class Function:
346
    name: str
347
    description: Optional[str]
348
    parameters: Optional[dict]
349
```