promptfoo--promptfoo/site/docs/providers/mistral.md

sidebar_label, title, description, keywords

sidebar_label	title	description	keywords
Mistral AI	Mistral AI Provider - Complete Guide to Models, Reasoning, and API Integration	Configure Mistral AI Magistral reasoning models with multimodal capabilities, function calling, and OpenAI-compatible APIs	mistral ai magistral reasoning openai alternative llm evaluation function calling multimodal ai code generation mistral api

Mistral AI

The Mistral AI API provides access to cutting-edge language models that deliver exceptional performance at competitive pricing. Mistral offers a compelling alternative to OpenAI and other providers, with specialized models for reasoning, code generation, and multimodal tasks.

Mistral is particularly valuable for:

• Cost-effective AI integration with pricing up to 8x lower than competitors
• Advanced reasoning with Magistral models that show step-by-step thinking
• Code generation excellence with Codestral models supporting 80+ programming languages
• Multimodal capabilities for text and image processing
• Enterprise deployments with on-premises options requiring just 4 GPUs
• Multilingual applications with native support for 12+ languages

:::tip Why Choose Mistral?

Mistral's current catalog spans low-cost small models, native reasoning models, and frontier multimodal models such as Mistral Large 3 at $0.50/$1.50 per million tokens (input/output).

:::

API Key

To use Mistral AI, you need to set the MISTRAL_API_KEY environment variable, or specify the apiKey in the provider configuration.

Example of setting the environment variable:

export MISTRAL_API_KEY=your_api_key_here

Configuration Options

The Mistral provider supports extensive configuration options:

Basic Options

providers:
  - id: mistral:mistral-large-latest
    config:
      # Model behavior
      temperature: 0.7 # Creativity (0.0-2.0)
      top_p: 0.95 # Nucleus sampling (0.0-1.0)
      max_tokens: 4000 # Response length limit

      # Advanced options
      random_seed: 42 # Deterministic outputs
      frequency_penalty: 0.1 # Reduce repetition
      presence_penalty: 0.1 # Encourage diversity
      stop: ['END'] # Optional stop sequence(s)
      n: 1 # Number of completions
      reasoning_effort: high # high | none on adjustable reasoning models
      prompt_mode: reasoning # reasoning | null on native reasoning models
      prompt_cache_key: shared-prefix # Reuse Mistral's server-side prompt cache across requests

safe_prompt is still accepted for compatibility, but Mistral now recommends inline guardrails instead.

JSON Mode

Force structured JSON output:

providers:
  - id: mistral:mistral-large-latest
    config:
      response_format:
        type: 'json_object'
      temperature: 0.3 # Lower temp for consistent JSON

tests:
  - vars:
      prompt: "Extract name, age, and occupation from: 'John Smith, 35, engineer'. Return as JSON."
    assert:
      - type: is-json
      - type: javascript
        value: JSON.parse(output).name === "John Smith"

Authentication Configuration

providers:
  # Option 1: Environment variable (recommended)
  - id: mistral:mistral-large-latest

  # Option 2: Direct API key (not recommended for production)
  - id: mistral:mistral-large-latest
    config:
      apiKey: 'your-api-key-here'

  # Option 3: Custom environment variable
  - id: mistral:mistral-large-latest
    config:
      apiKeyEnvar: 'CUSTOM_MISTRAL_KEY'

  # Option 4: Custom endpoint
  - id: mistral:mistral-large-latest
    config:
      apiHost: 'custom-proxy.example.com'
      apiBaseUrl: 'https://custom-api.example.com/v1'

Advanced Model Configuration

providers:
  # Reasoning model with optimal settings
  - id: mistral:magistral-medium-latest
    config:
      temperature: 0.7
      top_p: 0.95
      max_tokens: 40960

  # Adjustable reasoning on general-purpose models
  - id: mistral:mistral-medium-3.5
    config:
      reasoning_effort: high
      response_format:
        type: json_schema
        json_schema:
          name: answer
          schema:
            type: object
            properties:
              answer:
                type: string
            required: [answer]

  # Code generation with FIM support
  - id: mistral:codestral-latest
    config:
      temperature: 0.2 # Low for consistent code
      max_tokens: 8000
      stop: ['```'] # Stop at code block end

  # Current multimodal configuration
  - id: mistral:mistral-large-2512
    config:
      temperature: 0.5
      max_tokens: 2000

  # Recommended inline guardrails
  - id: mistral:mistral-small-latest
    config:
      guardrails:
        - block_on_error: true
          moderation_llm_v2:
            custom_category_thresholds:
              sexual: 0.1
            ignore_other_categories: false
            action: block

Environment Variables Reference

Variable	Description	Example
MISTRAL_API_KEY	Your Mistral API key (required)	sk-1234...
MISTRAL_API_HOST	Custom hostname for proxy setup	api.example.com
MISTRAL_API_BASE_URL	Full base URL override	https://api.example.com/v1

Model Selection

You can specify which Mistral model to use in your configuration. The following models are available:

Chat Models

Current Models

Model	Context	Input Price	Output Price	Capabilities	Best For
mistral-medium-latest	256k	$1.50/1M	$7.50/1M	Text, vision, reasoning¹	Agentic and coding-heavy workloads
mistral-large-latest	256k	$0.50/1M	$1.50/1M	Text, vision	General-purpose multimodal tasks
mistral-small-latest	256k	$0.15/1M	$0.60/1M	Text, vision, reasoning¹	Hybrid instruct, reasoning, and coding
magistral-medium-latest	128k	$2.00/1M	$5.00/1M	Native reasoning, vision	Step-by-step reasoning
codestral-latest	256k	$0.30/1M	$0.90/1M	Code, FIM	Code generation and completion
devstral-medium-latest	256k	$0.40/1M	$2.00/1M	Code agents	Software-engineering agents (Devstral 2)
ministral-14b-latest	256k	$0.20/1M	$0.20/1M	Text, vision	Compact multimodal deployments
ministral-8b-latest	256k	$0.15/1M	$0.15/1M	Text, vision	Efficient on-prem/edge deployments
ministral-3b-latest	128k	$0.10/1M	$0.10/1M	Text, vision	Smallest multimodal deployments
open-mistral-nemo	128k	$0.15/1M	$0.15/1M	Text	Multilingual and research workloads

¹ Enable adjustable reasoning with reasoning_effort: high.

:::note Aliases move — pin a snapshot for stability

*-latest and bare aliases follow whatever snapshot Mistral currently points them at, so their price and behavior track the resolved model. Pin a dated snapshot (e.g. mistral-medium-2604) when you need stable pricing and behavior.

:::

Model aliases and snapshots

Alias	Resolves to
mistral-medium-latest, mistral-medium, mistral-medium-3, mistral-medium-3-5, mistral-medium-3.5	mistral-medium-2604 (Mistral Medium 3.5)
mistral-large-latest	mistral-large-2512 (Mistral Large 3)
mistral-small-latest, magistral-small-latest	mistral-small-2603 (Mistral Small 4)
magistral-medium-latest	magistral-medium-2509 (Magistral Medium)
codestral-latest, mistral-code-latest, mistral-code-fim-latest	codestral-2508 (Codestral)
devstral-latest, devstral-medium-latest, mistral-code-agent-latest	devstral-2512 (Devstral 2)
open-mistral-nemo, mistral-tiny-latest, mistral-tiny-2407	open-mistral-nemo-2407 (Mistral NeMo)

The magistral-small-latest alias now resolves to Mistral Small 4 (a hybrid model), not the standalone Magistral Small reasoning snapshot. Enable Small 4's reasoning with reasoning_effort: high.

Legacy Models (Deprecated or Retired)

promptfoo keeps these IDs so it can cost-score cached results. Retired IDs return an error if you call them today; deprecated IDs still work until their retirement date.

1. open-mistral-7b, mistral-tiny, mistral-tiny-2312 (retired)
2. mistral-small-2402 (retired)
3. mistral-medium-2312 (retired; bare mistral-medium now resolves to Mistral Medium 3.5)
4. mistral-medium-2505, mistral-medium-2508 (Mistral Medium 3 / 3.1, deprecated — succeeded by Mistral Medium 3.5)
5. mistral-small-2506 (Mistral Small 3.2, deprecated — succeeded by Mistral Small 4)
6. mistral-large-2402, mistral-large-2407 (retired)
7. codestral-2405, codestral-mamba-2407, open-codestral-mamba, codestral-mamba-latest (retired)
8. open-mixtral-8x7b, open-mixtral-8x22b, open-mixtral-8x22b-2404, mistral-small, mistral-small-2312 (retired)
9. pixtral-12b (retired — use a current vision model such as mistral-large-latest)
10. magistral-small-2506, magistral-small-2507 (retired); magistral-small-2509 — standalone reasoning snapshot, deprecated 2026-04-30, retiring 2026-07-31 (magistral-small-latest now resolves to Mistral Small 4)

mistral-tiny-2407 / mistral-tiny-latest are not legacy — they are current aliases of open-mistral-nemo (see the aliases table above).

Embedding Models

• mistral-embed - $0.10/1M tokens - 8k context
• codestral-embed (codestral-embed-2505) - $0.15/1M tokens - code-optimized embeddings

Select an embedding model with the mistral:embedding: prefix:

providers:
  - mistral:embedding:mistral-embed
  - mistral:embedding:codestral-embed

Here's an example config that compares different Mistral models:

providers:
  - mistral:mistral-medium-latest
  - mistral:mistral-small-latest
  - mistral:open-mistral-nemo-2407
  - mistral:magistral-medium-latest

Reasoning Models

Mistral's Magistral models are specialized native reasoning models. magistral-medium-latest currently points to the 2509 generation, which uses tokenized thinking chunks and a 128k context window. Mistral's public model card deprecated the standalone magistral-small-2509 snapshot on 2026-04-30 (retiring 2026-07-31); the magistral-small-latest alias now resolves to Mistral Small 4, whose reasoning mode you enable with reasoning_effort: high.

Key Features of Magistral Models

• Chain-of-thought reasoning: Models provide step-by-step reasoning traces before arriving at final answers
• Multilingual reasoning: Native reasoning capabilities across English, French, Spanish, German, Italian, Arabic, Russian, Chinese, and more
• Transparency: Traceable thought processes that can be followed and verified
• Domain expertise: Optimized for structured calculations, programmatic logic, decision trees, and rule-based systems

Magistral Model Variants

• Magistral Medium (magistral-medium-latest / magistral-medium-2509) — native reasoning
• Mistral Small 4 (mistral-small-latest / magistral-small-latest) — hybrid model; enable reasoning with reasoning_effort: high

Usage Recommendations

For reasoning tasks, consider using these parameters for optimal performance:

providers:
  - id: mistral:magistral-medium-latest
    config:
      temperature: 0.7
      top_p: 0.95
      max_tokens: 40960 # Recommended for reasoning tasks

n requests multiple completions where the target model supports them. Mistral notes that mistral-large-2512 does not currently support n > 1.

Multimodal Capabilities

Mistral offers vision-capable models that can process both text and images:

Image Understanding

Use a current multimodal chat model such as mistral-large-2512:

providers:
  - id: mistral:mistral-large-2512
    config:
      temperature: 0.7
      max_tokens: 1000

tests:
  - vars:
      prompt: 'What do you see in this image?'
      image: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...'

Supported Image Formats

• JPEG, PNG, GIF, WebP
• Maximum size: 20MB per image
• Resolution: Up to 2048x2048 pixels optimal

Function Calling & Tool Use

Mistral models support advanced function calling for building AI agents and tools:

providers:
  - id: mistral:mistral-large-latest
    config:
      temperature: 0.1
      tools:
        - type: function
          function:
            name: get_weather
            description: Get current weather for a location
            parameters:
              type: object
              properties:
                location:
                  type: string
                  description: City name
                unit:
                  type: string
                  enum: ['celsius', 'fahrenheit']
              required: ['location']

tests:
  - vars:
      prompt: "What's the weather like in Paris?"
    assert:
      - type: contains
        value: 'get_weather'

Tool Calling Best Practices

• Use low temperature (0.1-0.3) for consistent tool calls
• Provide detailed function descriptions
• Include parameter validation in your tools
• Handle tool call errors gracefully

Code Generation

Mistral's Codestral models excel at code generation across 80+ programming languages:

Fill-in-the-Middle (FIM)

providers:
  - id: mistral:codestral-latest
    config:
      temperature: 0.2
      max_tokens: 2000

tests:
  - vars:
      prompt: |
        <fim_prefix>def calculate_fibonacci(n):
            if n <= 1:
                return n
        <fim_suffix>

        # Test the function
        print(calculate_fibonacci(10))
        <fim_middle>
    assert:
      - type: contains
        value: 'fibonacci'

Code Generation Examples

tests:
  - description: 'Python API endpoint'
    vars:
      prompt: 'Create a FastAPI endpoint that accepts a POST request with user data and saves it to a database'
    assert:
      - type: contains
        value: '@app.post'
      - type: contains
        value: 'async def'

  - description: 'React component'
    vars:
      prompt: 'Create a React component for a user profile card with name, email, and avatar'
    assert:
      - type: contains
        value: 'export'
      - type: contains
        value: 'useState'

Complete Working Examples

Example 1: Multi-Model Comparison

description: 'Compare reasoning capabilities across Mistral models'

providers:
  - mistral:magistral-medium-latest
  - mistral:mistral-medium-3.5
  - mistral:mistral-large-latest
  - mistral:mistral-small-latest

prompts:
  - 'Solve this step by step: {{problem}}'

tests:
  - vars:
      problem: "A company has 100 employees. 60% work remotely, 25% work hybrid, and the rest work in office. If remote workers get a $200 stipend and hybrid workers get $100, what's the total monthly stipend cost?"
    assert:
      - type: llm-rubric
        value: 'Shows clear mathematical reasoning and arrives at correct answer ($13,500)'
      - type: cost
        threshold: 0.10

Example 2: Code Review Assistant

description: 'AI-powered code review using Codestral'

providers:
  - id: mistral:codestral-latest
    config:
      temperature: 0.3
      max_tokens: 1500

prompts:
  - |
    Review this code for bugs, security issues, and improvements:

    ```{{language}}
    {{code}}
    ```

    Provide specific feedback on:
    1. Potential bugs
    2. Security vulnerabilities  
    3. Performance improvements
    4. Code style and best practices

tests:
  - vars:
      language: 'python'
      code: |
        import subprocess

        def run_command(user_input):
            result = subprocess.run(user_input, shell=True, capture_output=True)
            return result.stdout.decode()
    assert:
      - type: contains
        value: 'security'
      - type: llm-rubric
        value: 'Identifies shell injection vulnerability and suggests safer alternatives'

Example 3: Multimodal Document Analysis

description: 'Analyze documents with text and images'

providers:
  - id: mistral:mistral-large-2512
    config:
      temperature: 0.5
      max_tokens: 2000

tests:
  - vars:
      prompt: |
        Analyze this document image and:
        1. Extract key information
        2. Summarize main points
        3. Identify any data or charts
      image_url: 'https://example.com/financial-report.png'
    assert:
      - type: llm-rubric
        value: 'Accurately extracts text and data from the document image'
      - type: length
        min: 200

Authentication & Setup

Environment Variables

# Required
export MISTRAL_API_KEY="your-api-key-here"

# Optional - for custom endpoints
export MISTRAL_API_BASE_URL="https://api.mistral.ai/v1"
export MISTRAL_API_HOST="api.mistral.ai"

Getting Your API Key

1. Visit console.mistral.ai
2. Sign up or log in to your account
3. Navigate to API Keys section
4. Click Create new key
5. Copy and securely store your key

:::warning Security Best Practices

• Never commit API keys to version control
• Use environment variables or secure vaults
• Rotate keys regularly
• Monitor usage for unexpected spikes

:::

Performance Optimization

Model Selection Guide

Use Case	Recommended Model	Why
Cost-sensitive apps	mistral-small-latest	Best price/performance ratio
Complex reasoning	magistral-medium-latest	Step-by-step thinking
Code generation	codestral-latest	Specialized for programming
Vision tasks	mistral-large-2512	Current multimodal model
High-volume production	mistral-medium-latest	Balanced cost and quality

Context Window Optimization

providers:
  - id: mistral:magistral-medium-latest
    config:
      max_tokens: 8000 # Leave room for 128k input context
      temperature: 0.7

Cost Management

# Monitor costs across models
defaultTest:
  assert:
    - type: cost
      threshold: 0.05 # Alert if cost > $0.05 per test

providers:
  - id: mistral:mistral-small-latest # Most cost-effective
    config:
      max_tokens: 500 # Limit output length

Troubleshooting

Common Issues

Authentication Errors

Error: 401 Unauthorized

Solution: Verify your API key is correctly set:

echo $MISTRAL_API_KEY
# Should output your key, not empty

Rate Limiting

Error: 429 Too Many Requests

Solutions:

• Implement exponential backoff
• Use smaller batch sizes
• Consider upgrading your plan

# Reduce concurrent requests
providers:
  - id: mistral:mistral-large-latest
    config:
      timeout: 30000 # Increase timeout

Context Length Exceeded

Error: Context length exceeded

Solutions:

• Truncate input text
• Use models with larger context windows
• Implement text summarization for long inputs

providers:
  - id: mistral:mistral-medium-latest # 256k context
    config:
      max_tokens: 4000 # Leave room for input

Model Availability

Error: Model not found

Solution: Check model names and use latest versions:

providers:
  - mistral:mistral-large-latest # ✅ Use latest
  # - mistral:mistral-large-2402  # ❌ Retired

Debugging Tips

1. Enable debug logging:

   export DEBUG=promptfoo:*
   

2. Test with simple prompts first:

   tests:
     - vars:
         prompt: 'Hello, world!'
   

3. Check token usage:

   tests:
     - assert:
         - type: cost
           threshold: 0.01
   

Getting Help

• Documentation: docs.mistral.ai
• Community: Discord
• Support: support@mistral.ai
• Status: status.mistral.ai

Working Examples

Ready-to-use examples are available in our GitHub repository:

📋 Complete Mistral Example Collection

Run any of these examples locally:

npx promptfoo@latest init --example mistral

Individual Examples:

• AIME2024 Mathematical Reasoning - Evaluate Magistral models on advanced mathematical competition problems
• Model Comparison - Compare reasoning across Magistral and traditional models
• Function Calling - Demonstrate tool use and function calling
• JSON Mode - Structured output generation
• Code Generation - Multi-language code generation with Codestral
• Reasoning Tasks - Advanced step-by-step problem solving
• Multimodal - Vision capabilities with a current multimodal model (mistral-large-2512)

Quick Start

# Try the basic comparison
npx promptfoo@latest eval -c https://raw.githubusercontent.com/promptfoo/promptfoo/main/examples/mistral/promptfooconfig.comparison.yaml

# Test mathematical reasoning with Magistral models
npx promptfoo@latest eval -c https://raw.githubusercontent.com/promptfoo/promptfoo/main/examples/mistral/promptfooconfig.aime2024.yaml

# Test reasoning capabilities
npx promptfoo@latest eval -c https://raw.githubusercontent.com/promptfoo/promptfoo/main/examples/mistral/promptfooconfig.reasoning.yaml

:::tip Contribute Examples

Found a great use case? Contribute your example to help the community!

:::