Responses API | Mistral Docs

The Responses API lets you build with Mistral models using the OpenAI Responses format. You can generate text, ask questions about images and documents, call your own functions, and stream answers as they're generated. It works well whether you're starting a new application or bringing an existing Responses integration to Mistral.

For request parameters and response fields, see the API reference.

Supported features

Copy section link

Supported features

This Responses API is **stateless**. Your application keeps the conversation history and sends it in `input` with each request, including the `output` items from earlier responses.

In this public preview, you can use:

- **Text input and output:** strings and message arrays.

- **Image input:** image URLs and base64 data URLs in user messages and function results, with a vision-capable model.

- **File input:** HTTPS URLs, base64 data URLs, and uploaded file IDs in user messages and function results.

- **Structured output:** JSON mode and JSON Schema via `text.format`.

- **Streaming:** Responses events for text and function arguments.

- **Function calling:** client-executed functions, including namespaces.

- **Reasoning:**`reasoning.effort` and plaintext reasoning, depending on the model. See Reasoning for model details.

- **Input token counting:**`POST /v1/responses/input_tokens`.

Generate text

Copy section link

Generate text

To get started, install the Mistral SDK with `pip install -U mistralai` or `npm install @mistralai/mistralai@latest`, and set the `MISTRAL_API_KEY` environment variable to your Mistral API key.

Then send your prompt in `input`. Each response includes an `output` array, which can contain the model's messages, its reasoning, and any function calls. The examples below print just the answer text.

The examples use `mistral-large-4` with high reasoning effort and a 4,096-token output budget. If you switch to another model, pick a reasoning effort that it supports.

Python TypeScript cURL

``` import os from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"]) model = "mistral-large-4"

response = client.responses.create( model=model, input="Write a one-sentence greeting.", reasoning={"effort": "high"}, max_output_tokens=4096, )

def print_text(response): for item in response.output: if item.type == "message": for part in item.content: if part.type == "output_text": print(part.text)

print_text(response) ```

``` import os from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"]) model = "mistral-large-4"

response = client.responses.create( model=model, input="Write a one-sentence greeting.", reasoning={"effort": "high"}, max_output_tokens=4096, )

def print_text(response): for item in response.output: if item.type == "message": for part in item.content: if part.type == "output_text": print(part.text)

print_text(response) ```

The Python examples in the rest of this guide reuse `client`, `model`, and the `print_text` helper from above.

Understand an image

Copy section link

Understand an image

You can send images alongside your text in the same user message, so the model can answer questions about what it sees. Add an `input_image` item with an image URL or a base64 data URL, and use a model that supports vision.

``` response = client.responses.create( model=model, input=[{ "role": "user", "content": [ {"type": "input_text", "text": "What landmark is in this image?"}, { "type": "input_image", "image_url": "https://docs.mistral.ai/img/eiffel-tower-paris.jpg", "detail": "auto", }, ], }], reasoning={"effort": "high"}, max_output_tokens=4096, ) print_text(response) ```

To learn how to prepare images and which models support vision, see Vision.

Read a document

Copy section link

Read a document

You can send a document alongside a question to summarize its contents or find specific information. Include an `input_file` item in your message, as shown below.

``` response = client.responses.create( model=model, input=[{ "role": "user", "content": [ {"type": "input_text", "text": "Summarize the main findings of this paper."}, { "type": "input_file", "file_url": "https://arxiv.org/pdf/1805.04770", }, ], }], reasoning={"effort": "high"}, max_output_tokens=4096, ) print_text(response) ```

Set exactly one of `file_url`, `file_data`, or `file_id` for the file source. For upload and base64 preparation examples, see Document QnA.

Stream a response

Copy section link

Stream a response

With streaming, you can show the answer as it's generated instead of waiting for the whole response. Set `stream=True`, then read each event from `frame.data`. The `response.output_text.delta` events carry the answer text, so you can print them as they arrive.

``` stream = client.responses.create( model=model, input="Write a one-sentence greeting.", reasoning={"effort": "high"}, max_output_tokens=4096, stream=True, )

with stream: for frame in stream: event = frame.data if event.type == "response.output_text.delta": print(event.delta, end="", flush=True) ```

``` stream = client.responses.create( model=model, input="Write a one-sentence greeting.", reasoning={"effort": "high"}, max_output_tokens=4096, stream=True, )

with stream: for frame in stream: event = frame.data if event.type == "response.output_text.delta": print(event.delta, end="", flush=True) ```

The stream also includes events for reasoning, function calls, and the response lifecycle. A `response.completed` event tells you the response is finished. Your application should also handle `response.failed`, `response.incomplete`, and `error` events.

Manage conversation history

Copy section link

Manage conversation history

To have a conversation over several turns, send the earlier messages with each request so the model can follow along. After each response, add all of its `output` items to your history, followed by the next user message. In this example, the model answers a question and then translates its answer.

``` history = [{"role": "user", "content": "What is the capital of France?"}] response = client.responses.create( model=model, input=history, reasoning={"effort": "high"}, max_output_tokens=4096, )

history.extend(response.output) history.append({"role": "user", "content": "Translate that answer into French."}) response = client.responses.create( model=model, input=history, reasoning={"effort": "high"}, max_output_tokens=4096, ) print_text(response) ```

``` history = [{"role": "user", "content": "What is the capital of France?"}] response = client.responses.create( model=model, input=history, reasoning={"effort": "high"}, max_output_tokens=4096, )

Call functions

Copy section link

Call functions

Function calling lets the model ask your application for information or to take an action. Describe your functions in `tools`. When the model wants to use one, it returns the function name and arguments, and your application runs the function. In this example, the model asks to look up the status of an order.

``` tools = [{ "type": "function", "name": "get_delivery_status", "description": "Look up the delivery status of an order.", "parameters": { "type": "object", "properties": {"order_id": {"type": "string"}}, "required": ["order_id"], }, }] history = [{"role": "user", "content": "Where is order A123?"}] response = client.responses.create( model=model, input=history, reasoning={"effort": "high"}, max_output_tokens=4096, tools=tools, tool_choice={"type": "function", "name": "get_delivery_status"}, parallel_tool_calls=False, ) call = next(item for item in response.output if item.type == "function_call") print(call.name, call.arguments) ```

Once you have the result, send it back with the matching `call_id`, and the model will use it in its answer. Here, a sample delivery status stands in for a real lookup.

``` history.extend(response.output) history.append({ "type": "function_call_output", "call_id": call.call_id, "output": '{"order_id": "A123", "status": "in transit"}', }) response = client.responses.create( model=model, input=history, reasoning={"effort": "high"}, max_output_tokens=4096, tools=tools, ) print_text(response) ```

In a real application, validate the arguments before you run the function. To learn more, see Function Calling.

Count input tokens

Copy section link

Count input tokens

Want to know how large a request is before you generate a response? Count its input tokens with `POST /v1/responses/input_tokens`. Send the same model, input, instructions, and tools that you plan to use.

Python TypeScript cURL

``` count = client.responses.count_input_tokens( model=model, input="Write a one-sentence greeting.", ) print(count.input_tokens) ```

The result includes the number of input tokens in `input_tokens`.

#### Contents

- Supported features

- Generate text

- Understand an image

- Read a document

- Stream a response

- Manage conversation history

- Call functions

- Count input tokens