DEV Community

Cover image for Mistral Medium 3.5 API の使い方
Akira
Akira

Posted on • Originally published at apidog.com

Mistral Medium 3.5 API の使い方

Mistralは2026年4月29日にMedium 3.5をリリースしました。APIモデルIDはmistral-medium-3.5、エンドポイントはhttps://api.mistral.ai/v1/chat/completionsです。リクエスト形式はOpenAI標準に近いため、既存のOpenAI互換コードではベースURLとモデルIDを差し替えるだけで試せます。主な特徴は、256Kコンテキストウィンドウ、ネイティブビジョン、関数呼び出し、24言語対応、SWE-Bench Verifiedで77.6%です。

今すぐApidogを試す

このガイドでは、Mistral Medium 3.5 APIを実装するために必要な認証、主要パラメーター、Python/Nodeのサンプル、ビジョン入力、ツール呼び出し、JSONモード、ストリーミング、エラー処理、コスト管理、そしてプロンプト検証に使えるApidogのワークフローを順に説明します。関連ガイドとして、DeepSeek V4 APIの使用方法とGPT-5.5 APIの使用方法も参照できます。

TL;DR

  • エンドポイント: POST https://api.mistral.ai/v1/chat/completions
  • 認証: Authorization: Bearer <MISTRAL_API_KEY>
  • モデルID: mistral-medium-3.5
  • コンテキストウィンドウ: 256Kトークン
  • 価格: 入力100万トークンあたり$1.5、出力100万トークンあたり$7.5
  • 対応機能: 推論、ビジョン、ネイティブ関数呼び出し、構造化JSON出力、24言語対応
  • オープンウェイト: mistralai/Mistral-Medium-3.5-128B
  • ベンチマーク: SWE-Bench Verified 77.6%、τ³-Telecom 91.4
  • 現行モデルとA/Bテストする場合は、Apidogをダウンロードし、APIキーを秘密変数として保存して、呼び出しごとのコスト差を確認します。

Medium 3.5で変更された点

Medium 3は、128Kコンテキストのテキスト専用モデルでした。Medium 3.5では、コンテキストが256Kに拡張され、ビジョンと関数呼び出しがネイティブに統合されています。

また、Mistral初の旗艦マージモデルとして、指示理解、推論、コーディングを単一の重みセットで処理します。用途ごとにチャット用・推論用チェックポイントを切り替える必要がありません。

Mistral Medium 3.5 overview

実装上、特に重要なのは次の3点です。

  1. SWE-Bench Verified 77.6%

    コード修正やパッチ生成のユースケースで有利です。

  2. τ³-Telecom 91.4

    マルチターンのエージェント対話やツール使用に向いています。

  3. 256Kコンテキスト

    中規模コードベース、長いログ、会議文字起こし、PDF相当の長文を1回のリクエストに含めやすくなります。

ただし、価格はMedium 3より高くなります。Medium 3は入力$0.40/M、出力$2.00/Mでしたが、Medium 3.5は入力$1.5/M、出力$7.5/Mです。大量処理にはMedium 3、精度や長文理解が必要な処理にはMedium 3.5、というルーティングを前提に設計するとコストを制御しやすくなります。

前提条件

最初のAPI呼び出しの前に、次を準備します。

  1. console.mistral.aiでMistralアカウントを作成し、支払い方法を登録します。残高がない場合、APIは402 Payment Requiredを返します。
  2. 請求対象プロジェクトにスコープされたAPIキーを作成します。本番環境では、アカウント全体のキーよりもプロジェクトキーを使う方が安全です。
  3. PythonまたはNode.jsのSDKを用意します。Mistral公式SDKのほか、OpenAI SDKもベースURLを変更することで利用できます。
  4. リクエストを安全に再実行するためのAPIクライアントを用意します。最初はcurlで十分ですが、キーをシェル履歴に残さず、リクエストボディを管理するにはApidogを使うと便利です。

Apidog workflow

環境変数にAPIキーを設定します。

export MISTRAL_API_KEY="..."
Enter fullscreen mode Exit fullscreen mode

エンドポイントと認証

Mistralのチャット補完APIは、次のエンドポイントを使います。

POST https://api.mistral.ai/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

認証はBearerトークンです。

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-medium-3.5",
    "messages": [
      {
        "role": "user",
        "content": "Explain dense merged checkpoints in two sentences."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

成功すると、主に次のフィールドを含むJSONが返ります。

  • id: リクエスト追跡用ID
  • choices: モデルの応答
  • usage.prompt_tokens: 入力トークン数
  • usage.completion_tokens: 出力トークン数
  • usage.total_tokens: 合計トークン数

エラー時は、codeとmessageを含むerrorエンベロープが返ります。形状はOpenAI互換に近いため、既存のエラーパーサーを再利用しやすいです。

リクエストパラメーター

mistral-medium-3.5でよく使うパラメーターは以下です。

パラメーター タイプ 値 注意事項
model 文字列 mistral-medium-3.5 必須
messages 配列 role/contentのペア 必須。OpenAI互換スキーマ
temperature 浮動小数点数 0〜1.5 Mistralは汎用で0.7、コードで0.3を推奨
top_p 浮動小数点数 0〜1 デフォルトは1.0
max_tokens 整数 1〜コンテキスト制限 出力長を制限
stream 真偽値 true / false SSEストリーミングを有効化
tools 配列 OpenAIツール仕様 ネイティブ関数呼び出し
tool_choice 文字列またはオブジェクト auto、any、none、特定ツール ツール使用を制御。強制はrequiredではなくany
response_format オブジェクト {"type":"json_object"}またはJSONスキーマ 構造化出力
random_seed 整数 任意の整数 再現性のため。OpenAIのseedではない
safe_prompt 真偽値 true / false Mistralの安全プロンプトを追加
presence_penalty 浮動小数点数 -2〜2 繰り返されるトピックにペナルティ
frequency_penalty 浮動小数点数 -2〜2 繰り返されるトークンにペナルティ

OpenAIから移行する場合、特に注意する差分は2つです。

OpenAI:  tool_choice="required"
Mistral: tool_choice="any"
Enter fullscreen mode Exit fullscreen mode 
OpenAI:  seed
Mistral: random_seed
Enter fullscreen mode Exit fullscreen mode

それ以外の多くのパラメーターは、ほぼ同じ感覚で使えます。

Pythonクライアント

Mistral公式Python SDKを使う例です。

import os
from mistralai import Mistral

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

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {"role": "system", "content": "Reply in code only."},
        {"role": "user", "content": "Write a Rust function that debounces events."},
    ],
    temperature=0.3,
    max_tokens=2048,
)

print("Content:", response.choices[0].message.content)
print("Total tokens:", response.usage.total_tokens)

cost = (
    response.usage.prompt_tokens * 1.5 / 1_000_000
    + response.usage.completion_tokens * 7.5 / 1_000_000
)

print("Cost estimate (USD):", cost)
Enter fullscreen mode Exit fullscreen mode

既存コードがOpenAI SDKに依存している場合は、ベースURLとモデルIDを変更します。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MISTRAL_API_KEY"],
    base_url="https://api.mistral.ai/v1",
)

response = client.chat.completions.create(
    model="mistral-medium-3.5",
    messages=[
        {"role": "user", "content": "Hello, Mistral."}
    ],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

プロバイダー非依存の実装を維持したい場合はOpenAI SDKルートが簡単です。一方、Mistral固有機能を明示的に扱いたい場合は、公式mistralai SDKを選ぶと扱いやすくなります。

Nodeクライアント

Node.jsでMistral公式SDKを使う例です。

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({
  apiKey: process.env.MISTRAL_API_KEY,
});

const response = await client.chat.complete({
  model: "mistral-medium-3.5",
  messages: [
    {
      role: "user",
      content: "Explain dense merged checkpoints in plain English.",
    },
  ],
  temperature: 0.7,
});

console.log(response.choices[0].message.content);
console.log("Usage:", response.usage);
Enter fullscreen mode Exit fullscreen mode

OpenAI SDK互換で呼び出す場合は、baseURLを差し替えます。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MISTRAL_API_KEY,
  baseURL: "https://api.mistral.ai/v1",
});

const response = await client.chat.completions.create({
  model: "mistral-medium-3.5",
  messages: [
    {
      role: "user",
      content: "Hello, Mistral.",
    },
  ],
});

console.log(response.choices[0].message.content);
Enter fullscreen mode Exit fullscreen mode

ストリーミング応答

ストリーミングを使うにはstream: trueを設定し、SSEチャンクを順に処理します。

stream = client.chat.stream(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "user",
            "content": "Stream a 300-word essay on merged checkpoints.",
        }
    ],
)

for chunk in stream:
    delta = chunk.data.choices[0].delta.content or ""
    print(delta, end="", flush=True)
Enter fullscreen mode Exit fullscreen mode

レスポンス形状はOpenAIのストリーミング形式に近く、差分テキストはchoices[].delta.contentに入ります。プロンプトやモデルを比較する場合は、Apidogで同じリクエストを複製して、応答速度、品質、usageを横並びで確認すると判断しやすくなります。

ツール呼び出し

Medium 3.5はネイティブ関数呼び出しに対応しています。toolsに関数定義を渡すと、モデルが必要に応じて呼び出します。

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Return the current weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"},
                    "unit": {"type": "string", "enum": ["c", "f"]},
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "user",
            "content": "Weather in Lagos in Celsius?",
        }
    ],
    tools=tools,
    tool_choice="auto",
)

tool_call = response.choices[0].message.tool_calls[0]

print(tool_call.function.name)
print(tool_call.function.arguments)
Enter fullscreen mode Exit fullscreen mode

実装パターンは次の通りです。

  1. toolsで呼び出し可能な関数を定義する
  2. モデルからtool_callsを受け取る
  3. ローカルまたは外部APIで関数を実行する
  4. 結果をrole: "tool"メッセージとして追加する
  5. 再度APIを呼び出し、最終回答を生成する

このループはOpenAIのツール使用パターンとほぼ同じです。

JSONモードと構造化出力

構造化されたJSONが必要な場合は、response_formatを使います。

schema = {
    "type": "json_schema",
    "json_schema": {
        "name": "release_note",
        "schema": {
            "type": "object",
            "properties": {
                "title": {"type": "string"},
                "date": {"type": "string"},
                "bullets": {
                    "type": "array",
                    "items": {"type": "string"},
                },
            },
            "required": ["title", "date", "bullets"],
            "additionalProperties": False,
        },
        "strict": True,
    },
}

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "system",
            "content": "Reply with a single JSON object matching the schema.",
        },
        {
            "role": "user",
            "content": "Summarize today's Mistral Medium 3.5 release.",
        },
    ],
    response_format=schema,
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

厳密なスキーマが不要で、有効なJSONだけを返してほしい場合は次のようにします。

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "user",
            "content": "Return three API design tips as JSON.",
        }
    ],
    response_format={"type": "json_object"},
)
Enter fullscreen mode Exit fullscreen mode

本番環境では、モデル側の構造化出力に加えて、クライアント側でもPydanticやZodで検証すると安全です。

ビジョン入力

Medium 3.5は画像入力に対応しています。テキストと画像URLを同じmessages配列に含めます。

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What is in this image and what is it doing wrong?",
                },
                {
                    "type": "image_url",
                    "image_url": "https://example.com/diagram.png",
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

画像入力も入力トークンとして課金されます。正確なトークン数は解像度などに依存し、レスポンスのusage.prompt_tokensで確認できます。

大量の画像を処理する場合は、次を先に実装してください。

  • 画像ごとのprompt_tokensをログに残す
  • 必要な領域だけにトリミングする
  • 質問に答えられる最低限の解像度に下げる
  • 動画や連続スクリーンショットではフレームを間引く

ApidogでAPIコレクションを構築する

ターミナルだけでプロンプトを何度も試すと、APIキー管理、差分比較、コスト確認が難しくなります。実装検証では、次のようにApidogでコレクション化します。

  1. Apidogをダウンロードしてプロジェクトを作成します。
  2. {{MISTRAL_API_KEY}}を秘密変数として保存します。
  3. {{BASE_URL}}/chat/completionsへのPOSTリクエストを作成します。
  4. ヘッダーにAuthorization: Bearer {{MISTRAL_API_KEY}}を設定します。
  5. model、temperature、tool_choice、max_tokensを変数化します。
  6. 実行ごとにusageを確認します。
  7. レスポンス後スクリプトで、呼び出しごとのコストを計算します。

コスト計算式は次の通りです。

prompt_tokens * 1.5 / 1_000_000 + completion_tokens * 7.5 / 1_000_000
Enter fullscreen mode Exit fullscreen mode

すでにDeepSeek V4 APIコレクションをApidogで使っている場合は、コレクションを複製し、次の2箇所を変更するだけで比較できます。

BASE_URL: https://api.mistral.ai/v1
model:    mistral-medium-3.5
Enter fullscreen mode Exit fullscreen mode

GPT-5.5との比較でも同じ手順が使えます。

エラー処理

代表的なエラーと修正策は以下です。

コード 意味 修正策
400 不正なリクエスト JSONスキーマ、messages、toolsを検証する
401 無効なキー console.mistral.aiでキーを再生成する
402 支払いが必要 アカウントにチャージする、またはカードを追加する
403 モデルが許可されていない キーのプロジェクトスコープとモデルIDを確認する
422 パラメーター範囲外 max_tokens、tool_choiceなどを確認する
429 レート制限 待機し、指数バックオフで再試行する
500 サーバーエラー 一度再試行し、続く場合はステータスを確認する
503 過負荷 Mistral Medium 3へフォールバックするか、30秒待つ

リトライ方針は次のように分けます。

  • 429と5xx: 指数バックオフで再試行
  • 400、401、402、403、422: 自動再試行しない

4xxは多くの場合、コード、認証、スキーマ、パラメーターの問題です。再試行しても改善しないため、ログとリクエストボディを確認します。

コスト管理パターン

Medium 3.5は高性能ですが、Medium 3より高価です。次のパターンでコストを制御します。

1. デフォルトはMedium 3、必要時のみMedium 3.5へエスカレートする

安価なモデルで初回処理を行い、次の場合だけMedium 3.5にルーティングします。

  • バリデーションに失敗した
  • 信頼度が低い
  • 長いコンテキストが必要
  • ビジョン入力が必要
  • コード修正精度が重要

2. max_tokensを必ず設定する

出力トークンは入力より高価です。

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=messages,
    max_tokens=2000,
)
Enter fullscreen mode Exit fullscreen mode

256Kコンテキストは主に入力用です。必要以上に長い出力を許可しないようにします。

3. システムプロンプトを短くする

システムプロンプトは毎回課金されます。高頻度エンドポイントでは、長い前文を短縮するだけで入力コストが下がります。

4. usageを必ずログに残す

各呼び出しで次を記録します。

  • prompt_tokens
  • completion_tokens
  • total_tokens
  • USD換算コスト
  • モデルID
  • プロンプトバージョン

出力トークンが急増した場合にアラートを出すと、意図しない長文生成を早く検知できます。

5. ビジョンは選択的に使う

画像はトークン消費が増えやすいため、送信前に必要な領域だけを切り出します。スクリーンショット全体ではなく、UIの該当部分だけを渡す方がコストを抑えやすいです。

Medium 3.5と他のMistralティアの比較

2026年4月下旬時点のMistralラインナップは以下です。

モデル コンテキスト 入力 $/M 出力 $/M ビジョン 最適な用途
mistral-small 32K $0.10 $0.30 いいえ 大量分類、軽いチャット
mistral-medium-3 128K $0.40 $2.00 いいえ 大量スループット、長時間チャット
mistral-medium-3.5 256K $1.5 $7.5 はい 推論、コード、ビジョン、エージェント
mistral-large 128K $2.00 $6.00 限定的 フロンティアレベルのテキスト推論

Medium 3.5は、長いコンテキスト、ビジョン、推論、ツール使用を1つのモデルで扱いたい場合に適しています。モデル名ではなく、ワークロード要件で選ぶのが実装上は安全です。

他のプロバイダーからの移行

OpenAI SDKを使っている場合、最小変更はベースURLとモデルIDです。

- base_url="https://api.openai.com/v1"
- model="gpt-5.5"
+ base_url="https://api.mistral.ai/v1"
+ model="mistral-medium-3.5"
Enter fullscreen mode Exit fullscreen mode

DeepSeekからの移行も同様です。

- base_url="https://api.deepseek.com/v1"
- model="deepseek-v4-pro"
+ base_url="https://api.mistral.ai/v1"
+ model="mistral-medium-3.5"
Enter fullscreen mode Exit fullscreen mode

ただし、次の2点は修正が必要です。

- tool_choice="required"
+ tool_choice="any"
Enter fullscreen mode Exit fullscreen mode 
- seed=123
+ random_seed=123
Enter fullscreen mode Exit fullscreen mode

本番トラフィックを切り替える前に、既存のテストスイートで差分を確認してください。可能であれば1日程度シャドウモードでMistralに同じリクエストを流し、応答品質、レイテンシ、コストを比較してから昇格させます。

実際の使用例

Medium 3.5に向いているユースケースは次の通りです。

コードレビューアシスタント

SWE-Bench Verified 77.6%と256Kコンテキストにより、PR差分だけでなく周辺ファイルも含めたレビューに使いやすいです。

長いPDFに対するドキュメントQA

契約書、RFP、ポリシー文書などを細かくチャンク化せず、1回のリクエストで扱えるケースが増えます。

マルチモーダルデータ抽出

領収書、スクリーンショット、図表から構造化フィールドを抽出できます。OCRとテキストモデルを別々に組み合わせるより、実装が単純になります。

ツール呼び出しを伴うエージェントループ

ネイティブ関数呼び出しにより、検索、DB参照、外部API呼び出しを含むワークフローを構築できます。

FAQ

APIでのMistral Medium 3.5のモデルIDは何ですか？

ホストされたAPIではmistral-medium-3.5を使います。Hugging Faceのチェックポイントはmistralai/Mistral-Medium-3.5-128Bです。

Medium 3.5はOpenAIと互換性がありますか？

近いですが、完全一致ではありません。エンドポイント形状、ヘッダー、多くのパラメーターはOpenAI互換に近いため、OpenAI Python/Node SDKはベースURLを変更して使えます。

主な差分は次の2つです。

  • tool_choice="required"ではなくtool_choice="any"
  • seedではなくrandom_seed

Medium 3.5をローカルで実行できますか？

はい。ウェイトは、大規模収益のカーブアウト付きModified MIT Licenseの下で公開されています。ただし128Bパラメーターのため、十分なGPUメモリが必要です。量子化されたGGUFビルドとしてunsloth/Mistral-Medium-3.5-128B-GGUFも利用できます。DeepSeek V4をローカルで実行する方法の構成パターンも参考になります。

ツール呼び出しを伴うストリーミングに対応していますか？

はい。OpenAIのストリーミングツール呼び出し形式に近い形で、delta.tool_callsにツール呼び出し引数の断片が返ります。ストリーム完了後に、それらを完全なJSONオブジェクトとして組み立てます。

送信前に入力トークン数を数えるにはどうすればよいですか？

正確なカウントには、mistral-common Pythonパッケージのトークナイザーを使用します。APIと同じトークナイザーを使うため、usage.prompt_tokensに近い値を事前に見積もれます。

本番環境ではどのコンテキスト長を想定すべきですか？

256Kは上限です。価格は入力トークン数に比例します。200Kトークンを送ると、生成開始前に入力だけで約$0.30かかります。通常の本番ワークロードでは32K未満に収め、必要な場合だけ長いコンテキストを使う設計が現実的です。

無料ティアはありますか？

Mistralは恒久的な無料ティアを公表していませんが、新規アカウントには少額のトライアルクレジットが付与される場合があります。類似モデルの無料利用パターンについては、DeepSeek V4 APIを無料で使う方法も参考になります。

Top comments (0)