Home
Studio

Responses API

i
Information

The Responses API is in public preview. If you encounter any issues or have feedback, please contact Mistral support.

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

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

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.

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

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

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

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)

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

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)
Call functions

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

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.

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.