API Responses

L'API Responses vous permet d'utiliser les modèles Mistral avec le format Responses d'OpenAI. Vous pouvez générer du texte, poser des questions sur des images et des documents, appeler vos propres fonctions et afficher les réponses en streaming au fur et à mesure de leur génération. Elle convient aussi bien pour démarrer une nouvelle application que pour connecter une intégration Responses existante à Mistral.

Pour les paramètres de requête et les champs de réponse, consultez la référence API.

Cette API Responses est sans état. Votre application garde l'historique de la conversation et l'envoie dans input à chaque requête, y compris les éléments output des réponses précédentes.

Dans cette préversion publique, vous pouvez utiliser :

• Entrée et sortie de texte : chaînes de caractères et tableaux de messages.
• Images en entrée : URL d'images et URL de données en base64 dans les messages utilisateur et les résultats de fonction, avec un modèle compatible avec la vision.
• Fichiers en entrée : URL HTTPS, URL de données en base64 et identifiants de fichiers téléversés dans les messages utilisateur et les résultats de fonction.
• Sorties structurées : mode JSON et JSON Schema via text.format.
• Streaming : événements Responses pour le texte et les arguments de fonction.
• Function calling : fonctions exécutées côté client, y compris les espaces de noms.
• Raisonnement : reasoning.effort et raisonnement en texte brut, selon le modèle. Consultez Raisonnement pour plus de détails sur les modèles.
• Comptage des tokens d'entrée : POST /v1/responses/input_tokens.

Pour commencer, installez le SDK Mistral avec pip install -U mistralai ou npm install @mistralai/mistralai@latest, puis définissez la variable d'environnement MISTRAL_API_KEY avec votre clé API Mistral.

Envoyez ensuite votre prompt dans input. Chaque réponse contient un tableau output, qui peut inclure les messages du modèle, son raisonnement et d'éventuels appels de fonction. Les exemples ci-dessous affichent uniquement le texte de la réponse.

Les exemples utilisent mistral-large-4 avec un effort de raisonnement élevé et un budget de sortie de 4 096 tokens. Si vous utilisez un autre modèle, choisissez un effort de raisonnement qu'il prend en charge.

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)

Les exemples Python de la suite de ce guide réutilisent client, model et la fonction print_text définis plus haut.

Vous pouvez envoyer des images avec votre texte dans le même message utilisateur, pour que le modèle réponde à des questions sur ce qu'il voit. Ajoutez un élément input_image avec une URL d'image ou une URL de données en base64, et utilisez un modèle compatible avec la 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)

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)

Pour savoir comment préparer vos images et quels modèles prennent en charge la vision, consultez Vision.

Vous pouvez envoyer un document avec une question pour résumer son contenu ou trouver des informations précises. Ajoutez un élément input_file dans votre message, comme dans l'exemple ci-dessous.

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)

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)

Définissez exactement un champ parmi file_url, file_data et file_id pour la source du fichier. Pour les exemples de téléversement et de préparation en base64, consultez Document QnA.

Avec le streaming, vous pouvez afficher la réponse au fur et à mesure de sa génération, sans attendre la réponse complète. Définissez stream=True, puis lisez chaque événement dans frame.data. Les événements response.output_text.delta contiennent le texte de la réponse : vous pouvez donc l'afficher dès qu'il 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)

Le flux contient aussi des événements de raisonnement, d'appel de fonction et de cycle de vie de la réponse. Un événement response.completed indique que la réponse est terminée. Votre application doit aussi gérer les événements response.failed, response.incomplete et error.

Pour une conversation sur plusieurs tours, envoyez les messages précédents avec chaque requête afin que le modèle puisse suivre le fil. Après chaque réponse, ajoutez tous ses éléments output à votre historique, puis le message utilisateur suivant. Dans cet exemple, le modèle répond à une question, puis traduit sa réponse.

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,
)

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)

L'appel de fonction permet au modèle de demander des informations à votre application ou de lui faire effectuer une action. Décrivez vos fonctions dans tools. Lorsque le modèle veut en utiliser une, il renvoie le nom de la fonction et ses arguments, et votre application l'exécute. Dans cet exemple, le modèle demande l'état de livraison d'une commande.

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)

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)

Une fois le résultat obtenu, renvoyez-le avec le call_id correspondant, et le modèle l'utilisera dans sa réponse. Ici, un état de livraison fictif remplace une vraie recherche.

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)

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)

Dans une vraie application, validez les arguments avant d'exécuter la fonction. Pour en savoir plus, consultez Function Calling.

Vous voulez connaître la taille d'une requête avant de générer une réponse ? Comptez ses tokens d'entrée avec POST /v1/responses/input_tokens. Envoyez le même modèle, la même entrée, les mêmes instructions et les mêmes outils que ceux que vous comptez utiliser.

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

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

Le résultat indique le nombre de tokens d'entrée dans input_tokens.