Цепочка подключения Mistral API короткая: Base URL, ключ и название модели достаточно для первого вызова. Сложности обычно вызывает не код, а три детали: полный ли адрес указан, актуальна ли версия модели, образуют ли ключ и вход правильную пару.

Ниже разбирается официальный вход https://api.mistral.ai/v1, затем выполняются первые вызовы через curl и Python, после чего рассматриваются потоковый вывод, JSON-режим, вызов инструментов, типичные ошибки и чек-лист перехода с прямого подключения на ZSQH AI Gateway.

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

1. Перед подключением проверьте три вещи

Первое — источник ключа. Официальный ключ создаётся на https://console.mistral.ai и работает только с официальным входом; ключ шлюза создаётся в консоли ZSQH и работает только с входом шлюза.

Второе — Base URL. Официальный вход: https://api.mistral.ai/v1, полный путь чат-дополнения: https://api.mistral.ai/v1/chat/completions.

Третье — название модели. Mistral одновременно предоставляет псевдонимы -latest и фиксированные версии с датой; смысл у них разный. Псевдоним меняется вместе с официальной версией по умолчанию, фиксированная версия лучше подходит для регрессионных сравнений в production.

Только после проверки этих трёх пунктов пишите код. В обратном порядке легко застрять в цикле проб и ошибок между 401 и 404.

2. 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.

OpenAI-совместимый вход ZSQH AI Gateway — https://ai.zhongshangqihang.com/v1, правила пути те же. При переключении меняйте только base_url и api_key, не допускайте их пересечения.

3. Названия моделей: псевдоним или фиксированная версия

По состоянию на октябрь 2026 года официальный quickstart использует 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 указывает на текущую официальную версию по умолчанию и подходит для быстрой проверки и некритичных задач, но при смене версии поведение может измениться;
  • фиксированное имя с датой или поколением указывает на конкретную версию, подходит для production, позволяет сравнивать релизы и откатываться.

Разные официальные страницы обновляются не синхронно; конкретную версию псевдонима уточняйте в консоли или списке моделей на момент вызова. Перед подключением можно вызвать client.models.list() в SDK или проверить консоль — не копируйте названия моделей из старых статей.

При использовании ZSQH AI Gateway названия моделей определяются страницей цены на модели. Шлюз может сопоставлять имена upstream-моделей, поэтому прямое копирование официального названия не всегда сработает.

4. Первый 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 есть текст, значит ключ, Base URL и название модели верны. При 401 сначала проверьте ключ и заголовки; при 404 — путь и название модели; при 402 — состояние биллинга.

5. Вызов из 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. Форма запроса Mistral близка к OpenAI Chat Completions, и в сообществе такой подход распространён; однако официальная документация не позиционирует Mistral API как «OpenAI-совместимый продукт», поэтому набор поддерживаемых параметров, структура ошибок и расширенные поля всё равно определяются официальным API reference. Перед запуском проверьте реальными запросами каждый используемый параметр — не предполагайте, что все параметры OpenAI работают.

6. Потоковый вывод

Чат-интерфейсу обычно нужен вывод по мере генерации. В 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": "Напиши пример на Python для чтения CSV"}],
    )
    for chunk in stream:
        delta = chunk.data.choices[0].delta.content
        if delta:
            print(delta, end="", flush=True)

Потоковый ответ использует data-only SSE и завершается data: [DONE]. В коде нужно обработать три вещи: пустые приращения, отключение клиента и повтор по тайм-ауту. Не записывайте в базу каждое приращение — сначала соберите полный текст, затем сохраните результат.

7. 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 с tool_call_id и снова вызовите модель, пока она не даст финальный ответ. Многораундовые вызовы инструментов нужно обрабатывать циклом, а не одним проходом.

8. Типичные ошибки и диагностика

Ошибка Частая причина Что делать
400 Тело запроса не валидный JSON, отсутствует model или messages Сначала проверьте минимальное тело через curl
401 Ключ отсутствует, неверен, истёк или не соответствует входу Проверьте заголовок Bearer и источник ключа
402 Проблема биллинга: баланс, лимит расходов, неудачный платёж Проверьте счёт и квоты в консоли
403 У аккаунта или workspace нет прав на модель Проверьте workspace, права на модель и пакет
404 Неверный путь или модель/ресурс не существует Уточните /v1/chat/completions и название модели
422 JSON валиден, но значения параметров неверны Проверьте типы, допустимые значения и длину массивов
429 Превышены лимиты скорости, токенов или параллелизма Используйте экспоненциальную задержку и читайте Retry-After
500/503 Сбой или временная перегрузка сервера Подождите и повторите; при постоянной ошибке смотрите статус-страницу

429 не обходится созданием «нескольких ключей». Официальный сервис считает квоту по аккаунту, workspace или пакету, и несколько ключей часто делят один лимит. Правильный подход — снизить параллелизм, добавить экспоненциальную задержку, разнести пакетные задачи по времени и при необходимости перейти на более высокий пакет.

9. Чек-лист перехода с официального канала на шлюз

  1. Создайте аккаунт в ZSQH AI Gateway, сгенерируйте ключ шлюза и храните его отдельно от официального.
  2. Замените base_url на https://ai.zhongshangqihang.com/v1 и одновременно замените api_key.
  3. Заново сверьте названия моделей по странице цены на модели, не переносите официальные имена автоматически.
  4. Сохраните исходное тело запроса, сначала удалите расширенные параметры, не поддерживаемые шлюзом, затем добавляйте их по одному.
  5. Сравните вывод, время и usage на одном наборе реальных промптов, наблюдайте от трёх до семи дней.
  6. Оставьте официальное прямое подключение резервным каналом и подготовьте переключатель отката.
  7. Следите за 401, 429, 5xx и тайм-аутами; при аномалии сначала переключайте канал, затем разбирайтесь.

Миграция — не «смена адреса». Сопоставление моделей, поддержка параметров, потоковое поведение и правила биллинга могут различаться; сначала проверьте на небольшом трафике, затем переводите production.

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

Нужно ли указывать /v1 в Base URL?

Официальный вход требует /v1, то есть https://api.mistral.ai/v1. Полный путь чат-дополнения — https://api.mistral.ai/v1/chat/completions. В OpenAI SDK base_url указывается до /v1, а /chat/completions SDK добавит сам — не пишите его вручную повторно.

Использовать -latest или фиксированную версию?

Для быстрой проверки можно взять псевдоним вроде mistral-large-latest, чтобы не искать номер версии. В production лучше использовать фиксированное имя с датой или поколением: поведение воспроизводимо, а откат проще. В любом случае перед запуском проверьте доступность в официальной документации или консоли.

Можно ли работать с Mistral API через OpenAI SDK?

Форма запроса близка: если указать base_url как https://api.mistral.ai/v1 и подставить ключ Mistral, обычно всё работает. Но официально сервис не позиционируется как OpenAI-совместимый продукт, поэтому отдельные параметры и структура ошибок могут отличаться. Сначала проверьте минимальный запрос, затем по одному проверьте расширенные параметры, которые использует проект.

Почему в JSON-режиме приходит не объект?

JSON-режим обеспечивает корректность JSON, но content возвращается строкой и требует разбора. Сначала выполните json.loads(), затем проверку по схеме; явное требование JSON и структуры полей в промпте снижает число пустых полей и отклонений формата.

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

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

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