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

# Mistral AI

Use the [Mistral AI API](https://docs.mistral.ai/api/) for chat, reasoning, code generation, and image understanding. Check [Mistral's model catalog](https://docs.mistral.ai/getting-started/models/) for capabilities and availability.

For Mistral-hosted [Z.ai GLM 5.3](https://docs.mistral.ai/models/zai-glm-5-3), use `mistral:zai-glm-5-3`. Promptfoo includes standard input and output pricing for this model.

## 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:

```sh
export MISTRAL_API_KEY=your_api_key_here
```

## Configuration Options

The Mistral provider supports extensive configuration options:

### Basic Options

```yaml
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 accepted for compatibility, but Mistral recommends inline
`guardrails` instead.

### JSON Mode

Force structured JSON output:

```yaml
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

```yaml
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

````yaml
providers:
  # Adjustable reasoning on a current general-purpose model
  - 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
````

:::note

Mistral's `config.guardrails` field enables upstream inline input guardrails, but it does not enable Promptfoo's [`guardrails` assertion](/docs/configuration/expected-outputs/guardrails). Promptfoo sends the configuration without normalizing successful or HTTP 403 guardrail results into the required top-level response. Use a custom target or transform to assert on the native result. If `block_on_error` is enabled, distinguish a moderation-service failure from a policy violation instead of counting both as a match. Call a moderation endpoint separately for output filtering.

:::

### 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. Mistral adds and retires
models regularly, so use its [model overview](https://docs.mistral.ai/models/overview) as the
source of truth for availability and pricing.

### 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 |
| `codestral-latest`      | 128k    | $0.30/1M                       | $0.90/1M     | Code, FIM                | Code generation and completion         |
| `labs-leanstral-1-5`    | 256k    | $0 (Public Preview)            | $0           | Text, tools              | Lean 4 proof engineering               |
| `voxtral-small-2507`    | 32k     | $0.10/1M + $0.004/audio minute | $0.40/1M     | Text, audio              | Audio-aware chat                       |
| `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`   | 256k    | $0.10/1M                       | $0.10/1M     | Text, vision             | Smallest multimodal deployments        |

¹ Enable adjustable reasoning with `reasoning_effort: high`.

Leanstral 1.5 is scheduled to retire September 30, 2026. The [Voxtral Small estimate](https://docs.mistral.ai/models/voxtral-small-25-07)
adds $0.004 per audio minute when the API reports `usage.prompt_audio_seconds`, alongside text
input and output token charges. If audio duration is omitted, only the token subtotal is available.
Token price overrides apply to the token charges; the reported audio duration is billed separately.

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

`*-latest` aliases follow whatever model Mistral currently points them at, so their price and
behavior track the resolved model. Use a versioned ID such as `mistral-medium-3-5` when you need
stable pricing and behavior.

:::

#### Model aliases and snapshots

| Published alias                                                      | Resolves to                               |
| -------------------------------------------------------------------- | ----------------------------------------- |
| `mistral-medium-latest`, `mistral-medium-3`, `mistral-medium-3-5`    | `mistral-medium-3-5` (Mistral Medium 3.5) |
| `mistral-large-latest`                                               | `mistral-large-2512` (Mistral Large 3)    |
| `mistral-small-latest`                                               | `mistral-small-2603` (Mistral Small 4)    |
| `codestral-latest`, `mistral-code-latest`, `mistral-code-fim-latest` | `codestral-2508` (Codestral)              |

For compatibility, promptfoo also cost-scores `mistral-medium`, `mistral-medium-3.5`, and
`mistral-medium-2604` as Mistral Medium 3.5. The current model card does not publish these IDs,
but they are retained from live API and catalog verification for existing configs and cached
results.

<span id="legacy-models-deprecated-or-retired" />

#### Legacy models

Promptfoo retains some older prices for estimating costs from past evals. Retired models reject new requests. Check [Mistral's model catalog](https://docs.mistral.ai/getting-started/models/) before using an older snapshot.

### 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:

```yaml
providers:
  - mistral:embedding:mistral-embed
  - mistral:embedding:codestral-embed
```

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

```yaml
providers:
  - mistral:mistral-medium-3-5
  - mistral:mistral-small-2603
  - mistral:mistral-large-latest
```

## Reasoning Models

Mistral's **Magistral** models are deprecated native-reasoning models.
`magistral-small-latest` and `magistral-medium-latest` still point to their 2509 snapshots,
which use tokenized thinking chunks and 128k context windows. For new evals, use Mistral Small 4
or Mistral Medium 3.5 and enable reasoning with `reasoning_effort`.

### Key Features of Magistral Models

The legacy native-reasoning models emitted model-specific thinking chunks. Do not depend on that
wire format in new evals; migrate to `reasoning_effort` and assert on the final answer instead.

### Magistral Model Variants

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

### Usage Recommendations

For reasoning tasks, set the reasoning effort explicitly:

```yaml
providers:
  - id: mistral:mistral-medium-3-5
    config:
      reasoning_effort: high
      max_tokens: 8000
```

`n` requests multiple completions where the target model supports them. Mistral notes
that `mistral-large-2512` does not 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`:

```yaml
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:

```yaml
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)

```yaml
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

```yaml
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

```yaml title="promptfooconfig.yaml"
# yaml-language-server: $schema=https://promptfoo.dev/config-schema.json
description: 'Compare reasoning capabilities across Mistral models'

providers:
  - mistral:mistral-medium-3-5
  - mistral:mistral-small-2603
  - mistral:mistral-large-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 ($14,500)'
```

### Example 2: Code Review Assistant

````yaml title="promptfooconfig.yaml"
# yaml-language-server: $schema=https://promptfoo.dev/config-schema.json
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

```yaml
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

```bash
# 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](https://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                         |
| -------------------------- | -------------------- | --------------------------- |
| **Lower-cost comparisons** | `mistral-small-2603` | Lower listed token price    |
| **Complex reasoning**      | `mistral-medium-3-5` | Adjustable reasoning effort |
| **Code generation**        | `codestral-latest`   | Specialized for programming |
| **Vision tasks**           | `mistral-large-2512` | Current multimodal model    |

### Context Window Optimization

```yaml
providers:
  - id: mistral:mistral-medium-3-5
    config:
      max_tokens: 8000 # Leave room for 256k input context
      temperature: 0.7
```

### Cost Management

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

providers:
  - id: mistral:mistral-small-2603
    config:
      max_tokens: 500 # Limit output length
```

## Troubleshooting

### Common Issues

#### Authentication Errors

```
Error: 401 Unauthorized
```

**Solution**: Verify your API key is correctly set:

```bash
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

The Mistral provider has no `timeout` config option. Request timeouts come from the
`REQUEST_TIMEOUT_MS` environment variable (default 300000), and concurrency is controlled by the
`--max-concurrency` flag:

```bash
REQUEST_TIMEOUT_MS=600000 promptfoo eval --max-concurrency 1
```

#### Context Length Exceeded

```
Error: Context length exceeded
```

**Solutions**:

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

```yaml
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:

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

### Debugging Tips

1. **Enable debug logging**:

   ```bash
   export DEBUG=promptfoo:*
   ```

2. **Test with simple prompts first**:

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

3. **Check token usage**:
   ```yaml
   tests:
     - assert:
         - type: cost
           threshold: 0.01
   ```

### Getting Help

- **Documentation**: [docs.mistral.ai](https://docs.mistral.ai)
- **Community**: [Discord](https://discord.gg/mistralai)
- **Support**: [support@mistral.ai](mailto:support@mistral.ai)
- **Status**: [status.mistral.ai](https://status.mistral.ai)

## Working Examples

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

### 📋 [Complete Mistral Example Collection](https://github.com/promptfoo/promptfoo/tree/main/examples/mistral)

Run any of these examples locally:

```bash
npx promptfoo@latest init --example mistral
```

**Individual Examples:**

- **[AIME2024 Mathematical Reasoning](https://github.com/promptfoo/promptfoo/blob/main/examples/mistral/promptfooconfig.aime2024.yaml)** - Evaluate Magistral models on advanced mathematical competition problems
- **[Model Comparison](https://github.com/promptfoo/promptfoo/blob/main/examples/mistral/promptfooconfig.comparison.yaml)** - Compare reasoning across Magistral and traditional models
- **[Function Calling](https://github.com/promptfoo/promptfoo/blob/main/examples/mistral/promptfooconfig.tool-use.yaml)** - Demonstrate tool use and function calling
- **[JSON Mode](https://github.com/promptfoo/promptfoo/blob/main/examples/mistral/promptfooconfig.json-mode.yaml)** - Structured output generation
- **[Code Generation](https://github.com/promptfoo/promptfoo/blob/main/examples/mistral/promptfooconfig.code-generation.yaml)** - Multi-language code generation with Codestral
- **[Reasoning Tasks](https://github.com/promptfoo/promptfoo/blob/main/examples/mistral/promptfooconfig.reasoning.yaml)** - Advanced step-by-step problem solving
- **[Multimodal](https://github.com/promptfoo/promptfoo/blob/main/examples/mistral/promptfooconfig.multimodal.yaml)** - Vision capabilities with a current multimodal model (`mistral-large-2512`)

### Quick Start

```bash
# 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](https://github.com/promptfoo/promptfoo/tree/main/examples) to help the community!

:::