Получение Mistral API Key занимает немного времени: регистрация, вход в консоль, одно нажатие создания — и ключ у вас. Настоящие проблемы начинаются после: к какому workspace относится ключ, какие коннекторы ему доступны, где его хранить, когда ротировать и почему при верно скопированном ключе всё равно возвращается 401.

Ниже в практическом порядке разобраны создание ключа, права, переменные окружения, ротация и диагностика 401, а также различия между официальным ключом и ключом ZSQH AI Gateway.

Примечание: Mistral, Mistral AI и названия моделей — товарные знаки Mistral AI. Статья не связана с Mistral AI отношениями подчинения; материал опирается на публичную документацию и распространённую практику по состоянию на октябрь 2026 года. Квоты, права и продуктовая структура могут меняться; ориентируйтесь на официальную консоль и страницу цены на модели.

1. Сначала разделите: официальный ключ и ключ шлюза не взаимозаменяемы

У Mistral API Key обычно два источника.

Первый — ключ, созданный в официальной консоли Mistral, работает с официальным входом https://api.mistral.ai/v1. Второй — ключ, созданный в консоли ZSQH AI Gateway, работает с входом шлюза https://ai.zhongshangqihang.com/v1.

Формат ключей может быть похожим, но принадлежность совершенно разная. Официальный ключ соответствует только официальному входу, ключ шлюза — только входу шлюза; смешивание обычно даёт 401. При диагностике начинайте с этого.

2. Регистрация и вход в консоль

Официальный процесс выполняется в браузере:

  1. Откройте https://console.mistral.ai, зарегистрируйтесь или войдите в аккаунт Mistral.
  2. Пройдите необходимые шаги, включая подтверждение почты, и войдите в Studio.
  3. По официальной документации доступ к API при первом использовании включён по умолчанию и карта не требуется, но действуют ограничения по расходу и скорости.
  4. В левой навигации найдите API Keys.
  5. Нажмите Create new key.
  6. Заполните Name, выберите Expiration и Connector access scope.
  7. Ещё раз нажмите Create new key, чтобы завершить создание.
  8. Сразу скопируйте полный ключ в менеджер паролей или серверный сервис управления секретами.

Самый важный пункт: полный ключ показывается только один раз в окне успешного создания. После закрытия окна консоль не выдаст полное значение. Если не сохранили — придётся создать новый ключ и удалить старый.

3. Как заполнять три параметра при создании

Name (имя) различает назначение и не влияет на права. Укажите среду и приложение, например mistral-dev-chat, mistral-prod-batch. Имя вроде «тест» через несколько месяцев не позволит понять, можно ли ключ удалять.

Expiration (срок действия) определяет срок жизни ключа. Официально администратор может задать политику истечения; при отключённой политике можно выбрать бессрочный ключ. На практике для бизнес-ключа надёжнее задать конкретную дату, например ротацию раз в квартал. Не делайте все ключи бессрочными только ради удобства.

Connector access scope (доступ к коннекторам) имеет два варианта:

  • Shared connectors only: доступ только к коннекторам, общим для текущего workspace, без личных коннекторов создателя. Официально рекомендуется для автоматизации.
  • Private and shared connectors: доступ и к личным коннекторам создателя, и к общим. Выбирайте только при реальной необходимости в личных коннекторах.

После создания workspace, область коннекторов и срок действия ключа напрямую изменить нельзя. Для корректировки нужно создать замену и удалить старый ключ. Поэтому лишние десять секунд проверки при создании экономят миграцию позже.

4. Workspace и права: ключ не является глобальным пропуском

Ключи Mistral привязаны к workspace. Каждый ключ привязан к workspace, выбранному при создании; квота, лимиты скорости и область ресурсов workspace действуют на этот ключ. Иными словами, границы прав ключа зависят не только от него самого, но и от workspace.

Администратор организации может на admin.mistral.ai/organization/api-keys просматривать, создавать, ротировать и удалять ключи всех workspace, а также задавать политику истечения на уровне организации. Обычный разработчик управляет своими ключами в меню пользователя Studio или на странице API Keys.

Базовый принцип безопасности — минимальные права: если приложению нужны только общие коннекторы, не выбирайте приватные; если можно создать отдельный бизнес-ключ, не переиспользуйте административный ключ. Если административный ключ попал в бизнес-код, потом его очень трудно локализовать.

5. Поместите ключ в переменные окружения

Не записывайте ключ в исходный код, фронтендный 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="ваш-ключ". В production лучше применять Secrets Manager облачного провайдера, Kubernetes Secret или аналогичный сервис, а не держать файл .env на сервере постоянно.

При копировании ключа не добавляйте пробелы и переводы строки; в логах фиксируйте только префикс или хеш; вызовы с фронтенда должны идти через бэкенд, не передавайте ключ в браузер.

6. Ротация и отзыв: действуйте по порядку, не удаляйте старый ключ первым

Цель ротации — сначала передать трафик новому ключу, затем вывести старый, чтобы не прерывать работу. Рекомендуемый порядок:

  1. Создайте новый ключ в том же workspace и укажите дату ротации в имени.
  2. Запишите новый ключ в сервис управления секретами или переменные окружения платформы развёртывания.
  3. Выпустите сервис и убедитесь, что новые инстансы прочитали новый ключ.
  4. Проверьте новый ключ минимальным запросом, затем некоторое время наблюдайте долю ошибок и расход.
  5. Убедившись, что трафик больше не идёт через старый ключ, удалите его в консоли.
  6. Проверьте недавний расход и логи на подозрительные вызовы.

При подозрении на утечку порядок обратный: сначала удалите или отключите старый ключ, чтобы остановить ущерб, затем создайте новый и разверните. Официальная документация считает удаление способом отзыва: после удаления ключ сразу перестаёт действовать. В инциденте утечки не стоит «сначала понаблюдать»: каждая минута с утёкшими учётными данными может приносить расходы.

7. Диагностика 401: сначала определите тип сбоя

401 означает ошибку аутентификации, но причина не только в «неверном ключе». Таблица ниже помогает идти по порядку.

Симптом Частая причина Что делать
401 Unauthorized В запросе нет заголовка Authorization Добавьте Authorization: Bearer <Key>
401 Unauthorized Ключ скопирован не полностью, с пробелом или переводом строки Скопируйте заново, проверьте скрытые символы
401 Unauthorized Ключ истёк или удалён Проверьте статус в консоли, при необходимости создайте новый
401 Unauthorized Официальный ключ указан с адресом шлюза или наоборот Ключ и Base URL должны быть с одной платформы
401 Unauthorized Запрос отправлен по неверному пути Официальный путь чата — /v1/chat/completions
403 Forbidden У workspace ключа нет прав на модель или ресурс Проверьте workspace, права на модель и область коннекторов

Различайте соседние ошибки: 402 обычно связана с биллингом — недостаток баланса, лимит расходов или неудачный платёж; 403 означает нехватку прав, а не недействительный ключ; 429 — срабатывание лимита скорости, нужна задержка и повтор, а не смена ключа. Смешивая 401, 402, 403 и 429 в одной диагностике, легко затянуть простое решение.

8. Прямое официальное подключение или шлюз ZSQH

Если вы используете только Mistral и официальный аккаунт с оплатой работают нормально, прямое подключение — понятный выбор: консоль, документация и счета в одном месте, границы проблем проще.

Если в одном проекте нужны Mistral, Claude, GPT, Gemini и другие модели, либо требуется пополнение в юанях и единый счёт, ZSQH AI Gateway снижает затраты на управление. Шлюз предоставляет OpenAI-совместимый вход; при смене модели в основном меняется поле model, а ключ и адрес заменяются парой. Доступные модели и биллинг — на странице цены на модели; новый пользователь может создать аккаунт на странице регистрации или сразу открыть https://ai.zhongshangqihang.com.

В любом случае не храните официальный ключ и ключ шлюза под одним именем переменной. Используйте MISTRAL_API_KEY и ZSQH_API_KEY и явно выбирайте вход.

9. Семь проверок перед запуском

  • Ключ присутствует только на сервере; во фронтенд-пакете, логах и репозитории нет полного значения.
  • Для разработки, staging и production используются разные ключи, желательно в разных workspace.
  • У каждого ключа есть понятное назначение и срок действия.
  • Область коннекторов выбрана по минимальным правам; бизнес-ключ не использует права администратора.
  • В аккаунте настроены напоминания о расходе или лимит, чтобы аномальные вызовы быстро обнаруживались.
  • В логах остаётся только префикс или хеш ключа, без полных учётных данных.
  • При увольнении сотрудника, потере устройства или подозрении на утечку есть чёткий порядок отзыва и ротации.

Частые вопросы

Можно ли получить Mistral API Key бесплатно?

Официальная документация указывает, что доступ к API при первом использовании включён по умолчанию и карта не требуется, но в режиме Free действуют ограничения по расходу и скорости. Актуальные квоты и ограничения — в консоли. Для долгой работы или высокой нагрузки обычно нужен платный тариф.

Можно ли снова посмотреть полный ключ после создания?

Нет. Полный ключ показывается один раз в окне успешного создания, после закрытия получить его нельзя. Если не сохранили — создайте новый ключ и удалите старый. Сохраняйте ключ сразу в менеджер паролей или сервис управления секретами.

Можно ли использовать один ключ в нескольких приложениях?

Технически можно, но не рекомендуется. При общем ключе для разных приложений и сред невозможно определить источник вызовов и отозвать доступ отдельно. Надёжнее разделять ключи по приложению и среде, как минимум отделяя тест от production.

Всегда ли 401 означает неверный ключ?

Нет. 401 возвращается при отсутствии ключа, неверном формате, истечении, удалении, отсутствии Bearer в заголовке; несовпадение ключа и Base URL по платформе также часто проявляется как 401. Сначала проверьте статус ключа, затем адрес входа, затем заголовки.

Можно ли использовать официальный ключ с адресом шлюза ZSQH?

Нет. Официальный ключ соответствует https://api.mistral.ai/v1, ключ шлюза — https://ai.zhongshangqihang.com/v1. При смене входа ключ и Base URL меняются вместе, иначе обычно возвращается 401.

Полезные материалы: