mistral-ai

name	mistral-ai
description	Complete guide for integrating Mistral AI APIs - text generation, vision, agents, OCR, STT, TTS, document processing, embeddings, function calling, and structured outputs.
category	ai-ml
tags	["mistral","ai","llm","vision","ocr","stt","tts","agents","embeddings","function-calling","document-ai"]
version	1.0.0
author	OpenClaw & Hermes Agent
metadata	{"homepage":"https://docs.mistral.ai","api_base":"https://api.mistral.ai/v1","python_sdk":"mistralai"}

Mistral AI Integration Skill

Complete reference for building applications with Mistral AI's comprehensive suite of AI capabilities.

Overview

Mistral AI provides state-of-the-art models and APIs for:

• Text Generation - Chat completions, reasoning, code generation
• Vision - Multimodal understanding of images and text
• Agents - Autonomous AI agents with tool use and handoffs
• Document AI - OCR, structured data extraction, document Q&A
• Audio - Speech-to-text (STT) and Text-to-speech (TTS)
• Embeddings - Text and code embeddings for RAG
• Function Calling - Connect models to external tools
• Structured Outputs - JSON mode and custom schemas

Quick Start

from mistralai import Mistral

# Initialize client
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Simple chat completion
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

When to Use This Skill

Use this skill when:

• Building applications with Mistral AI models
• Implementing multimodal AI (text + vision + audio)
• Creating autonomous AI agents
• Processing documents with OCR and structured extraction
• Converting speech to text or text to speech
• Implementing RAG with embeddings
• Adding tool use / function calling to applications

Available Models

General-Purpose Models (ALL support Vision)

Model	ID	Capabilities
Mistral Large 3	mistral-large-2512	Text, Vision, Function Calling, Agents
Mistral Medium 3.1	mistral-medium-2508	Text, Vision, Function Calling
Mistral Small 4	mistral-small-2603	Text, Vision, Function Calling
Mistral Small 3.2	mistral-small-2506	Text, Vision, Function Calling

Specialized Models

Model	ID	Purpose
Devstral 2	devstral-2512	Code generation, software engineering
Codestral	codestral-2508	Code completion
Magistral Medium 1.2	magistral-medium-2509	Reasoning, step-by-step thinking
Magistral Small 1.2	magistral-small-2509	Small reasoning model

Vision Models (All Support Vision)

Model	ID	Notes
Mistral Large 3	mistral-large-2512	Best vision + reasoning
Mistral Medium 3.1	mistral-medium-2508	Balanced vision + performance
Mistral Small 3.2	mistral-small-2506	Fast, cost-effective vision
Ministral 3 14B	ministral-14b-2512	Efficient vision + text
Ministral 3 8B	ministral-8b-2512	Balanced performance
Ministral 3 3B	ministral-3b-2512	Edge/embedded use

Audio Models

Model	ID	Purpose
Voxtral Mini Transcribe	voxtral-mini-2507	Speech-to-text (batch)
Voxtral Mini Transcribe 2	voxtral-mini-2602	Speech-to-text v2 (batch)
Voxtral Realtime	voxtral-realtime-2602	Live transcription
Voxtral TTS	voxtral-tts-2603	Text-to-speech
Voxtral Small	voxtral-small-2507	Audio input for chat

Document & OCR

Model	ID	Purpose
OCR 3	mistral-ocr-2512	Document OCR and extraction

Embeddings

Model	ID	Purpose
Mistral Embed	mistral-embed	Text embeddings
Codestral Embed	codestral-embed-2505	Code embeddings

Core Capabilities

1. Text & Chat Completions

See references/text-completion.md

Basic usage:

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum computing"}
    ],
    temperature=0.7,
    max_tokens=1000
)

2. Vision (Multimodal)

See references/vision.md

All general-purpose models support vision - Small, Medium, and Large.

Analyze images:

messages = [{
    "role": "user",
    "content": [
        {"type": "text", "text": "What's in this image?"},
        {"type": "image_url", "image_url": "https://example.com/image.jpg"}
    ]
}]

# Any of these work for vision:
response = client.chat.complete(model="mistral-small-2506", messages=messages)   # Fast, cheap
response = client.chat.complete(model="mistral-medium-2508", messages=messages)  # Balanced
response = client.chat.complete(model="mistral-large-2512", messages=messages)   # Best quality

3. Agents & Agentic Workflows

See references/agents.md

Create autonomous agents:

# Create an agent with built-in tools
agent = client.agents.create(
    model="mistral-large-latest",
    tools=[
        {"type": "web_search"},
        {"type": "code_interpreter"}
    ]
)

# Run conversation
response = client.agents.complete(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "Research the latest AI papers"}]
)

4. Document AI & OCR

See references/ocr.md

Process documents:

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://example.com/document.pdf"
    },
    table_format="markdown",
    include_image_base64=True
)

# Access extracted content
for page in ocr_response.pages:
    print(page.markdown)

5. Speech-to-Text (STT)

See references/stt.md

Transcribe audio:

with open("audio.mp3", "rb") as f:
    transcription = client.audio.transcriptions.complete(
        model="voxtral-mini-latest",
        file={"content": f, "file_name": "audio.mp3"},
        timestamp_granularities=["word"],
        diarize=True
    )
print(transcription.text)

6. Text-to-Speech (TTS)

See references/tts.md for full TTS documentation.

Quick Reference: 10 preset voices available - see references/preset-voices.json for complete list with IDs.

Most commonly used preset voices:

• Paul - Neutral (Recommended default): c69964a6-ab8b-4f8a-9465-ec0925096ec8
• Paul - Happy: 1024d823-a11e-43ee-bf3d-d440dccc0577
• Paul - Excited: 5940190b-f58a-4c3e-8264-a40d63fd6883
• Jane - Sarcasm (Female): a3e41ea8-020b-44c0-8d8b-f6cc03524e31

Generate speech:

speech = client.audio.speech.create(
    model="voxtral-tts-2603",
    input="Hello, this is a test.",
    voice="c69964a6-ab8b-4f8a-9465-ec0925096ec8",  # Paul - Neutral (recommended)
    response_format="mp3"
)

with open("output.mp3", "wb") as f:
    f.write(speech.content)

7. Embeddings

See references/embeddings.md

Create embeddings:

embeddings = client.embeddings.create(
    model="mistral-embed",
    input=["First text", "Second text"]
)

# Calculate similarity
import numpy as np
vec1 = np.array(embeddings.data[0].embedding)
vec2 = np.array(embeddings.data[1].embedding)
similarity = np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2))

8. Function Calling

See references/function-calling.md

Define and use tools:

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get weather for a location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string", "description": "City name"}
            },
            "required": ["location"]
        }
    }
}]

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
    tools=tools,
    tool_choice="auto"
)

9. Structured Outputs

See references/structured-outputs.md

Get JSON responses:

from pydantic import BaseModel

class Person(BaseModel):
    name: str
    age: int
    occupation: str

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Extract info: John is 30 and works as an engineer."}],
    response_format={"type": "json_object"}
)

import json
person = Person(**json.loads(response.choices[0].message.content))

Installation

pip install mistralai

Set environment variable:

export MISTRAL_API_KEY="your-api-key"

Get API key from: https://console.mistral.ai

Pricing (as of 2026)

Model	Input	Output
Mistral Large 3	$2/M tokens	$6/M tokens
Mistral Medium 3.1	$1.5/M tokens	$4.5/M tokens
Mistral Small 4	$0.2/M tokens	$0.6/M tokens
Mistral Small 3.2	$0.1/M tokens	$0.3/M tokens
Ministral 3 8B	$0.1/M tokens	$0.3/M tokens
Voxtral TTS	-	$16/M chars
OCR	$5/1000 pages	-
Embeddings	$0.1/M tokens	-

See full pricing: https://mistral.ai/products/la-plateforme#pricing

Best Practices

1. Model Selection

   • Use mistral-large-latest for complex reasoning
   • Use mistral-small-latest for cost-effective, fast responses
   • Use devstral-latest for code generation tasks

2. Context Management

   • Large 3: 128k context window
   • Medium 3.1: 128k context window
   • Small models: 32k-128k context window

3. Rate Limits

   • Varies by tier (Free/Developer/Enterprise)
   • Batch API available for large-scale processing

4. Error Handling

   from mistralai.exceptions import MistralAPIError, MistralConnectionError
   
   try:
       response = client.chat.complete(...)
   except MistralAPIError as e:
       print(f"API Error: {e}")
   except MistralConnectionError as e:
       print(f"Connection Error: {e}")
   

5. Streaming Responses

   stream = client.chat.stream(
       model="mistral-large-latest",
       messages=messages
   )
   for chunk in stream:
       print(chunk.data.choices[0].delta.content, end="")
   

Code Examples

See templates/ directory for complete code examples:

• basic_chat.py - Simple chat completion
• vision_analysis.py - Image understanding
• agent_workflow.py - Autonomous agent
• ocr_processing.py - Document OCR
• stt_transcription.py - Speech-to-text
• tts_generation.py - Text-to-speech
• rag_system.py - RAG with embeddings
• function_tools.py - Function calling
• structured_data.py - Structured outputs

Testing & Troubleshooting

See references/rest-api-testing.md for:

• Testing APIs with curl when Python SDK unavailable
• Common errors and solutions
• TTS/STT troubleshooting
• Vision image URL requirements
• Response parsing tips

Additional Resources

• Documentation: https://docs.mistral.ai
• API Reference: https://docs.mistral.ai/api
• Cookbooks: https://docs.mistral.ai/cookbooks
• Discord: https://discord.gg/mistralai
• GitHub: https://github.com/mistralai

Quick Reference Files

• references/preset-voices.json - Complete list of 10 TTS preset voices with IDs
• references/tts.md - Full TTS documentation including voice cloning

Updates

Last updated: April 2026 Mistral AI API version: v1

• Added complete preset voice list (10 voices)
• TTS now works without voice samples using preset voices