Mistral API 的接入链路很短：一个 Base URL、一个 Key、一个模型名，就能完成第一次调用。真正让人卡住的通常不是代码，而是三个细节——地址有没有写全、模型名是不是当前版本、Key 和入口是不是配成一对。

本文从官方入口 https://api.mistral.ai/v1 讲起，依次完成 curl 和 Python 第一次调用，再补充流式输出、JSON 模式、工具调用、常见报错，以及从官方直连迁到中商起航 AI 网关时的检查清单。

说明：Mistral、Mistral AI 及相关模型名称是 Mistral AI 的商标。本文与 Mistral AI 官方无隶属关系，模型、参数和额度可能随版本调整，请以官方文档和站内模型价格为准。

一、接入前确认三件事

第一是 Key 的来源。官方 Key 在 https://console.mistral.ai 创建，只能配官方入口；网关 Key 在中商起航控制台创建，只能配网关入口。

第二是 Base URL。官方入口是 https://api.mistral.ai/v1，聊天补全的完整路径是 https://api.mistral.ai/v1/chat/completions。

第三是模型名。Mistral 同时提供 -latest 别名和带日期的固定版本名，两者含义不同。别名会随官方切换默认版本而变化，固定版本更适合生产环境做回归对比。

这三件事确认完，再写代码。顺序反过来，很容易在 401 和 404 之间反复试错。

二、Base URL 与请求路径

官方 API 的基础地址是：

https://api.mistral.ai/v1

聊天补全使用 POST /v1/chat/completions。请求头需要两项：

Authorization: Bearer <MISTRAL_API_KEY>
Content-Type: application/json

如果你用官方 Python SDK，通常只需要传 api_key，SDK 会自动拼接地址。如果用 OpenAI SDK，则把 base_url 设为 https://api.mistral.ai/v1，SDK 会在后面追加 /chat/completions。

这里最常见的错误是重复拼接：base_url 已经带了 /v1，请求路径又写一次 /v1/chat/completions，最后变成 /v1/v1/chat/completions，返回 404。另一个常见错误是把官方地址和网关地址混用，表现为 401。

中商起航 AI 网关的 OpenAI 兼容入口是 https://ai.zhongshangqihang.com/v1，路径规则相同。切换时只改 base_url 和 api_key，不要让两者交叉。

三、模型名：别名与固定版本怎么选

截至 2026 年 10 月，官方快速开始使用 mistral-large-latest，函数调用文档还列出了 mistral-medium-latest、mistral-small-latest 等别名。模型总览页给出的固定版本名包括 mistral-large-4（公开预览）、mistral-large-2512、mistral-medium-3-5、mistral-small-2603，以及 ministral-14b-2512、codestral-2508 等专用模型。

两类名字的差异在于：

  • -latest 别名指向官方当前的默认版本，适合快速验证和非关键业务，但默认版本变化时行为可能跟着变。
  • 带日期或代数的固定版本名指向明确版本，适合生产环境锁定行为，便于做发布对比和回滚。

官方不同页面更新节奏不完全一致，别名对应的具体版本以调用时控制台或模型列表返回为准。接入前可以用 SDK 的 client.models.list() 或控制台确认当前可用模型，不要照抄旧文章里的模型名。

如果使用中商起航 AI 网关，模型名以站内模型价格页面为准。网关可能对上游模型名做映射，直接把官方模型名搬过来不一定可用。

四、第一次 curl：先跑通最小请求

先设置环境变量，再发一条最短请求。max_tokens 给小一点，减少等待和干扰。

export MISTRAL_API_KEY="你的密钥"

curl https://api.mistral.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -d '{
    "model": "mistral-large-latest",
    "messages": [
      {"role": "user", "content": "只回复 OK"}
    ],
    "max_tokens": 32
  }'

返回 200，并且 choices[0].message.content 里有内容，说明 Key、Base URL、模型名三项都对。如果返回 401，先查 Key 和请求头；返回 404，先查路径和模型名；返回 402，先查账单状态。

五、Python 调用：Mistral SDK 与 OpenAI SDK

官方 Python SDK 的包名是 mistralai：

pip install mistralai

最小调用示例：

import os
from mistralai.client import Mistral

with Mistral(api_key=os.environ["MISTRAL_API_KEY"]) as client:
    response = client.chat.complete(
        model="mistral-large-latest",
        messages=[
            {"role": "system", "content": "你是中文技术助手，回答简洁。"},
            {"role": "user", "content": "用三句话解释什么是向量数据库。"},
        ],
        max_tokens=256,
    )

print(response.choices[0].message.content)
print(response.usage)

注意导入路径：当前 SDK 文档使用 from mistralai.client import Mistral，部分旧版本写作 from mistralai import Mistral。两者不要混着抄，报 ModuleNotFoundError 时先看安装的 SDK 版本和官方迁移说明。

如果你想复用现有的 OpenAI SDK 代码，可以把 base_url 指向 https://api.mistral.ai/v1，把 api_key 换成 Mistral Key。Mistral 的请求形状与 OpenAI Chat Completions 很接近，社区里这样用得很普遍；但官方文档并没有把 Mistral API 作为“OpenAI 兼容产品”来宣传，参数支持范围、错误结构和扩展字段仍以官方 API 参考为准。上线前用真实请求逐项验证，不要默认所有 OpenAI 参数都生效。

六、流式输出

聊天界面通常需要逐字返回。Mistral SDK 用 client.chat.stream(...)，返回的是事件流，正文增量在 chunk.data.choices[0].delta.content：

with Mistral(api_key=os.environ["MISTRAL_API_KEY"]) as client:
    stream = client.chat.stream(
        model="mistral-large-latest",
        messages=[{"role": "user", "content": "写一个读取 CSV 的 Python 示例"}],
    )
    for chunk in stream:
        delta = chunk.data.choices[0].delta.content
        if delta:
            print(delta, end="", flush=True)

流式响应使用 data-only SSE，最后以 data: [DONE] 结束。工程上要处理三件事：空增量、客户端断开、以及超时重试。不要在每个增量上做数据库写入，先拼接完整文本，结束后再落库。

七、JSON 模式、结构化输出与工具调用

JSON 模式使用 response_format={"type": "json_object"}。官方文档说明，除 codestral-mamba 外的当前模型都支持。开启后输出会被约束为合法 JSON，但 content 里是字符串形式的 JSON，仍需要自己 json.loads()。提示词里要明确写出“返回 JSON 对象”和期望字段，不要只依赖参数。

结构化输出适合字段固定的场景。官方 SDK 提供 client.chat.parse(...)，可以直接传入 Pydantic 模型，返回解析后的对象；如果走原始 JSON Schema，需要设置 strict: true，并在对象上设置 additionalProperties: false。字段越严格，模型自由发挥的空间越小，后续校验也越简单。

工具调用使用 tools 数组，tool_choice 可选 auto、any、none，parallel_tool_calls 控制是否允许并行。模型只负责返回工具名和参数，真正执行函数的是你的后端。拿到 tool_calls 后，把 assistant 消息原样追加回消息列表，再追加一条带 tool_call_id 的 tool 消息，然后再次调用模型，直到它给出最终回答。多轮工具调用要循环处理，不能只跑一轮。

八、常见报错与排查

报错 常见原因 处理
400 请求体不是合法 JSON，缺少 model 或 messages 先用 curl 验证最小请求体
401 Key 缺失、错误、过期，或与入口不匹配 检查 Bearer 头和 Key 来源
402 账单问题：余额、消费上限、付款失败 到控制台检查账单和额度
403 账号或工作区没有该模型权限 检查工作区、模型权限和套餐
404 路径写错，或模型/资源不存在 确认 /v1/chat/completions 和模型名
422 JSON 合法但参数值不合法 检查类型、枚举值和数组长度
429 超过速率、Token 或并发限制 指数退避，读取 Retry-After
500/503 服务端异常或暂时过载 短暂等待后重试，持续异常看状态页

429 不要靠“多建几把 Key”绕过。官方按账号、工作区或套餐维度统计额度，多把 Key 往往共享同一个限制。正确做法是降并发、做指数退避、把批量任务错峰，必要时再考虑更高套餐。

九、从官方迁到网关的检查清单

  1. 在中商起航 AI 网关创建账号，生成网关 Key，和官方 Key 分开保存。
  2. 把 base_url 改为 https://ai.zhongshangqihang.com/v1，同时更换 api_key。
  3. 按站内模型价格重新确认模型名，不要直接沿用官方名称。
  4. 保留原请求体，先删掉网关不支持的扩展参数，再逐项加回。
  5. 用同一批真实提示词对比输出、耗时和 usage，观察三到七天。
  6. 保留官方直连作为备用通道，写好回滚开关。
  7. 监控 401、429、5xx 和超时，异常时先切通道再排查。

迁移不是“改个地址就完事”。模型映射、参数支持、流式行为和计费口径都可能不同，先用小流量验证，再切生产。

常见问题

Base URL 到底要不要带 /v1？

官方入口要带 /v1，即 https://api.mistral.ai/v1。聊天补全的完整路径是 https://api.mistral.ai/v1/chat/completions。用 OpenAI SDK 时，base_url 写到 /v1 即可，SDK 会自己追加 /chat/completions，不要再手写一遍。

模型名用 -latest 还是固定版本？

快速验证可以用 mistral-large-latest 这类别名，省去查版本号。生产环境更建议用带日期或代数的固定版本名，行为可复现，出问题也容易回滚。无论用哪种，上线前都到官方文档或控制台确认当前可用性。

Mistral API 可以直接用 OpenAI SDK 吗？

请求形状接近，把 base_url 指向 https://api.mistral.ai/v1、换成 Mistral Key 通常可以跑通。但官方没有把它作为 OpenAI 兼容产品来宣传，个别参数和错误结构可能不同。建议先用最小请求验证，再逐项检查项目里用到的扩展参数。

JSON 模式为什么拿到的不是对象？

JSON 模式保证输出是合法 JSON，但返回的 content 是字符串，需要自己解析。先 json.loads()，再做 schema 校验；提示词里明确要求 JSON 和字段结构，能减少空字段和格式漂移。

官方 Key 能配中商起航网关地址吗？

不能。官方 Key 对应 https://api.mistral.ai/v1，网关 Key 对应 https://ai.zhongshangqihang.com/v1。迁移时 Key 和 Base URL 必须成对更换，混用通常会返回 401。

相关阅读：