Mistral API Key 获取教程：注册、创建与安全配置（2026）

Mistral API Key 的获取流程并不长：注册账号、进入控制台、点一次创建，就能拿到一串密钥。真正容易出问题的，是拿到 Key 之后的配置：它属于哪个工作区、能访问哪些连接器、应该放在哪里、什么时候轮换，以及为什么明明复制了 Key 还是返回 401。

本文按实际操作顺序，讲清 Key 创建、权限、环境变量、轮换和 401 排查，并说明官方 Key 与中商起航 AI 网关 Key 的区别。

说明：Mistral、Mistral AI 及相关模型名称是 Mistral AI 的商标。本文与 Mistral AI 官方无隶属关系，内容以 2026 年 10 月公开文档和常见实践为例；额度、权限与产品形态可能调整，请以官方控制台和站内模型价格为准。

一、先分清：官方 Key 和网关 Key 不能混用

Mistral API Key 常见有两种来源。

第一种是 Mistral 官方控制台创建的 Key，配合官方入口 https://api.mistral.ai/v1 使用。第二种是中商起航 AI 网关控制台创建的 Key，配合网关入口 https://ai.zhongshangqihang.com/v1 使用。

两套 Key 的格式可能相似，但归属完全不同。官方 Key 只对应官方入口，网关 Key 只对应网关入口，混用通常返回 401，排查时先确认这一点。

二、注册账号与进入控制台

官方流程如下，全程在浏览器里完成：

打开 https://console.mistral.ai，注册或登录 Mistral 账号。
按页面提示完成邮箱验证等必要步骤，进入 Studio 控制台。
首次使用时，官方文档说明 API 访问默认开启，不需要绑定信用卡，但会有用量和速率限制。
在左侧导航栏找到 API Keys。
点击 Create new key。
填写 Name，选择 Expiration 和 Connector access scope。
再次点击 Create new key 完成创建。
立即复制完整 Key，存进密码管理器或服务端密钥管理服务。

这里最重要的一条是：完整 Key 只在创建成功的弹窗里显示一次。关闭弹窗后，控制台不会再提供完整值。如果没保存，只能新建一把，然后把旧的删掉。

三、创建 Key 时三个选项怎么填

Name（名称） 用来区分用途，不影响权限。建议把环境和应用写进去，例如 mistral-dev-chat、mistral-prod-batch。只写“测试”之类的名字，几个月后很难判断该不该删。

Expiration（过期时间） 决定 Key 的有效期。官方允许管理员设置过期策略，策略关闭时可以选不过期。实际使用中，给业务 Key 设置一个明确的到期日更稳妥，例如按季度轮换。不要因为“省事”把所有 Key 都设成永久有效。

Connector access scope（连接器访问范围） 有两个选项：

Shared connectors only：只能访问共享给当前工作区的连接器，不能访问创建者私有的连接器。官方建议自动化场景使用这一项。
Private and shared connectors：同时访问创建者私有连接器和共享连接器。只有确实需要私有连接器时才选。

创建完成后，Key 所属的工作区、连接器范围和过期时间都不能直接修改。要调整只能新建一把替代 Key，再删除旧 Key。因此创建时多花十秒确认，比事后迁移更省事。

四、Workspace 与权限：Key 不是全局通行证

Mistral 的 Key 是工作区级别的。每把 Key 绑定创建时选择的工作区，工作区的配额、速率限制和资源范围都会作用在这把 Key 上。换句话说，Key 的权限边界不只取决于 Key 本身，还取决于它所在的工作区。

组织管理员可以在 admin.mistral.ai/organization/api-keys 统一查看、创建、轮换和删除各工作区的 Key，并设置组织级过期策略。普通开发者则可以在 Studio 的用户菜单或 API Keys 页面管理自己的 Key。

安全上的基本原则是最小权限：应用只需要共享连接器，就不要选私有连接器；能单独建一把业务 Key，就不要复用管理员 Key。管理员 Key 一旦进入业务代码，后面很难收口。

五、把 Key 放进环境变量

不要把 Key 写进源代码、前端 JavaScript、移动端包或公开仓库。推荐做法是放服务端环境变量，或者放密钥管理服务，由运行时注入。

# macOS / Linux：只在当前终端会话生效
export MISTRAL_API_KEY="你的密钥"

# 项目根目录的 .env 文件示例（记得把 .env 加入 .gitignore）
MISTRAL_API_KEY=你的密钥

Python 里读取：

import os

api_key = os.environ["MISTRAL_API_KEY"]

Windows PowerShell 使用 $env:MISTRAL_API_KEY="你的密钥"。生产环境更推荐用云厂商的 Secrets Manager、Kubernetes Secret 或类似的密钥管理服务，而不是把 .env 文件放在服务器上长期保留。

复制 Key 时不要带空格或换行；日志只记录前缀或哈希指纹；前端调用应经后端转发，不要把 Key 下发到浏览器。

六、轮换与吊销：按顺序做，不要先删旧 Key

轮换的目标是让新 Key 先接管流量，再让旧 Key 下线，避免业务中断。建议按下面的顺序操作：

在同一个工作区创建新 Key，名称标注轮换日期。
把新 Key 写入密钥管理服务或部署平台的环境变量。
发布服务，确认新实例已经读取到新 Key。
用一条最小请求验证新 Key 可用，再观察一段时间的错误率和用量。
确认没有流量再使用旧 Key 后，在控制台删除旧 Key。
检查最近的用量和日志，确认没有异常调用。

如果怀疑 Key 已经泄漏，顺序要反过来：先删除或停用旧 Key 止损，再创建新 Key 并部署。官方文档把删除作为吊销方式，删除后 Key 立即失效。不要在泄漏事件里“先观察一下”，凭证泄漏的每一分钟都可能产生费用。

七、401 排查：先分清是哪种失败

401 表示鉴权失败，但原因不止“Key 填错了”。下面这张表可以按顺序对照。

现象	常见原因	处理
401 Unauthorized	请求没带 `Authorization` 头	补上 `Authorization: Bearer <Key>`
401 Unauthorized	Key 复制不完整，带了空格或换行	重新复制，检查隐藏字符
401 Unauthorized	Key 已过期或被删除	在控制台确认状态，必要时新建
401 Unauthorized	官方 Key 配了网关地址，或反过来	Key 与 Base URL 必须来自同一平台
401 Unauthorized	请求发到了错误的路径	官方聊天路径是 `/v1/chat/completions`
403 Forbidden	Key 所在工作区没有该模型或资源权限	检查工作区、模型权限和连接器范围

还要区分几个相邻错误：402 通常和账单有关，例如余额不足、达到消费上限或付款失败；403 是权限不足，不是 Key 无效；429 是触发了速率限制，应该退避重试，而不是反复换 Key。把 401、402、403、429 混在一起排查，容易把简单问题拖长。

八、官方直连还是中商起航网关

如果你只使用 Mistral，官方账号和付款方式都能顺利使用，官方直连是清晰的选择：控制台、文档和账单都在一处，问题边界也简单。

如果你需要在一个项目里同时调用 Mistral、Claude、GPT、Gemini 等模型，或者希望用人民币充值和统一账单，中商起航 AI 网关会更省管理成本。网关提供 OpenAI 兼容入口，切换模型主要改 model 字段，Key 和地址成对更换即可。可用模型和计费方式见模型价格，新用户可以从注册页创建账号，也可以直接访问 https://ai.zhongshangqihang.com。

无论选哪种，都不要把官方 Key 和网关 Key 放进同一个环境变量名。建议分别用 MISTRAL_API_KEY 和 ZSQH_API_KEY，按入口显式选择。

九、上线前的七项检查

Key 只出现在服务端，前端包、日志和仓库里都没有完整值。
开发、预发、生产使用不同 Key，最好在不同工作区。
每把 Key 都有明确用途和到期时间。
连接器范围按最小权限选择，业务 Key 不使用管理员权限。
账户设置了用量提醒或消费上限，异常调用能及时发现。
日志只保留 Key 前缀或指纹，不保留完整凭证。
人员离职、设备丢失或怀疑泄漏时，有明确的吊销和轮换流程。

常见问题

Mistral API Key 可以免费获取吗？

官方文档说明，首次使用时 API 访问默认开启，不需要信用卡，但 Free 模式有用量和速率限制。具体额度和限制以官方控制台当前显示为准。长期或高并发使用通常需要开通付费方案。

Key 创建后还能重新查看完整值吗？

不能。完整 Key 只在创建成功的弹窗里显示一次，关闭后无法再次获取。如果没有保存，只能新建一把 Key，再删除旧的。建议创建后立即存入密码管理器或密钥管理服务。

一个 Key 可以给多个应用共用吗？

技术上可以，但不建议。不同应用、不同环境共用一个 Key，出问题时无法判断是谁在调用，也无法单独吊销。更稳妥的做法是按应用和环境拆分 Key，至少把测试和生产分开。

401 一定是 Key 错了吗？

不一定。Key 缺失、格式错误、过期、被删除、请求头没带 Bearer，都会返回 401；Key 与 Base URL 不属于同一平台也常表现为 401。先确认 Key 状态，再确认入口地址，最后检查请求头。

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

不能。官方 Key 只对应 https://api.mistral.ai/v1，网关 Key 只对应 https://ai.zhongshangqihang.com/v1。切换入口时，Key 和 Base URL 要一起更换，否则通常返回 401。