Текстовые модели MiniMax предоставляют OpenAI-совместимый интерфейс, поэтому существующему проекту на OpenAI SDK обычно достаточно изменить три вещи: Base URL, API Key и имя модели. На практике подключение чаще всего застревает на региональном домене, регистре имени модели, содержании рассуждения и параметрах токенов. Ниже порядок «адрес — модель — вызов — разбор ошибок — миграция», который доводит до первого успешного запроса.

Сразу вывод: официальный OpenAI-совместимый адрес заканчивается на /v1, чат-эндпоинт — /v1/chat/completions; имя модели должно точно совпадать с документацией; в новом коде лучше использовать max_completion_tokens и оставлять бюджет вывода на рассуждение.

Примечание: MiniMax — товарный знак своего правообладателя; статья носит технический характер. Имена моделей, интерфейсы, контекст и лимиты определяются официальной документацией MiniMax и страницей цены на модели. Имена моделей из примеров сверяйте в консоли перед использованием в production.

1. Base URL: сначала выберите регион и протокол

У MiniMax сейчас два набора доменов — китайский сайт и международный, а также три входа: OpenAI-совместимый, Anthropic-совместимый и нативный. Самый частый выбор — OpenAI-совместимый: международный сайт https://api.minimax.io/v1, китайский https://api.minimax.cn/v1, чат-эндпоинт POST /v1/chat/completions.

Если вы используете Anthropic SDK или инструменты вроде Claude Code, вендор рекомендует Anthropic-совместимый вход: международный https://api.minimax.io/anthropic, китайский https://api.minimax.cn/anthropic, эндпоинт сообщений POST /anthropic/v1/messages. Старый нативный интерфейс POST /v1/text/chatcompletion_v2 ещё существует, но для новых подключений лучше совместимый: параметры и экосистема единообразнее.

Сценарий Base URL Типичный эндпоинт
Официальный OpenAI-совместимый (международный) https://api.minimax.io/v1 POST /v1/chat/completions
Официальный OpenAI-совместимый (Китай) https://api.minimax.cn/v1 POST /v1/chat/completions
Официальный Anthropic-совместимый (международный) https://api.minimax.io/anthropic POST /anthropic/v1/messages
Официальный Anthropic-совместимый (Китай) https://api.minimax.cn/anthropic POST /anthropic/v1/messages
Нативный текстовый интерфейс https://api.minimax.io или https://api.minimax.cn POST /v1/text/chatcompletion_v2
Шлюз ZSQH https://ai.zhongshangqihang.com/v1 POST /v1/chat/completions

Адрес в таблице и ключ должны быть с одной платформы. Ключ китайского сайта на международном адресе обычно сразу даёт 401; ключ шлюза на официальном адресе — тоже. Ещё одна частая ошибка: Base URL уже содержит /v1, а путь дописывается ещё раз, и получается /v1/v1/chat/completions.

2. Имена моделей: регистр и версия должны совпадать

По состоянию на октябрь 2026 года в официальной документации текущие текстовые модели — MiniMax-M3.1-Flash и MiniMax-M3 с окном контекста 1 000 000 токенов. MiniMax-M3.1-Flash поддерживает регулировку глубины рассуждения; MiniMax-M3 — мультимодальная модель кодирования того же поколения.

Модели предыдущего поколения также указаны в документации: MiniMax-M2.7, MiniMax-M2.7-highspeed, MiniMax-M2.5, MiniMax-M2.5-highspeed, MiniMax-M2.1, MiniMax-M2.1-highspeed, MiniMax-M2 с контекстом 204 800 токенов. Отдельно есть MiniMax-M2-her с контекстом 64K. Имена чувствительны к регистру и дефисам — копируйте их, а не набирайте вручную.

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

3. curl: сначала один нестриминговый запрос

Подготовьте переменную окружения MINIMAX_API_KEY с ключом. Ниже пример для OpenAI-совместимого интерфейса китайского сайта; для международного замените домен на api.minimax.io, для шлюза — на адрес шлюза. Сначала не включайте стриминг: убедитесь в структуре ответа, потом добавляйте.

export MINIMAX_API_KEY="ваш-ключ"

curl "https://api.minimax.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-M3.1-Flash",
    "messages": [
      {"role": "system", "content": "Вы — краткий помощник."},
      {"role": "user", "content": "В трёх предложениях объясните, что такое Base URL."}
    ],
    "max_completion_tokens": 512,
    "stream": false
  }'

В возвращённом JSON choices[0].message.content — итоговый ответ. В серии M3 содержание рассуждения обычно находится в поле reasoning_content, а content содержит только финальный ответ. Не смешивайте их при отображении, если продукт специально не показывает ход рассуждения.

Если идёте через шлюз, меняйте адрес, ключ и имя модели вместе. Замена только одного элемента обычно приводит к метаниям между 401 и model not found.

4. Python: вызов через OpenAI SDK

После установки openai укажите base_url на совместимый адрес MiniMax. В примере адрес и модель вынесены в переменные окружения, чтобы легко переключаться между официальным входом и шлюзом.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MINIMAX_API_KEY"],
    base_url=os.environ.get("MINIMAX_BASE_URL", "https://api.minimax.cn/v1"),
)

stream = client.chat.completions.create(
    model=os.environ.get("MINIMAX_MODEL", "MiniMax-M3.1-Flash"),
    messages=[
        {"role": "system", "content": "Вы — краткий помощник."},
        {"role": "user", "content": "Напишите пример на Python: прочитать CSV и посчитать строки."},
    ],
    max_completion_tokens=1024,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    if getattr(delta, "reasoning_content", None):
        print(delta.reasoning_content, end="")
    if delta.content:
        print(delta.content, end="")

В потоковом ответе рассуждение находится в delta.reasoning_content, основной текст — в delta.content; при stream_options.include_usage = true последний чанк содержит usage. Разные версии SDK могут хранить неизвестные поля по-разному, поэтому перед чтением один раз выведите сырой ответ в тестовой среде.

5. Токены и параметры сэмплирования: не ограничивайтесь max_tokens

В новых подключениях используйте max_completion_tokens для ограничения вывода; max_tokens в официальной документации помечен как устаревший параметр и ещё может поддерживаться, но полагаться на него в новом коде не стоит. Токены рассуждения серии M3 также входят в лимит вывода: если лимит слишком мал, вернётся finish_reason: "length" и пустой content.

Основные параметры:

  • temperature: управляет случайностью, допустимый диапазон — по текущей документации; выход за него даёт 400.
  • top_p: по умолчанию 0.95 для серии M3 и 0.9 для M2.x; обычно регулируют только один из двух параметров.
  • reasoning_effort: серия M3 поддерживает low, medium, high, xhigh, max, по умолчанию max; снижение уменьшает задержку и выходные токены.
  • thinking: для M3.1-Flash рассуждение включено принудительно, передача disabled даёт 400; поддержка у других моделей — по документации.
  • n: поддерживается только 1; presence_penalty, frequency_penalty и подобные параметры могут игнорироваться.
  • Вызов инструментов: используйте tools, а не устаревший function_call; при многошаговом вызове возвращайте в историю полное сообщение assistant, включая tool_calls и содержание рассуждения.

Если задержка высокая, сначала снизьте reasoning_effort, затем сократите вход и лимит вывода; не меняйте модель сразу. У моделей с рассуждением качество и задержка обычно меняются вместе, и при верных параметрах во многих сценариях меньшая модель не нужна.

6. Частые ошибки: определяйте по статусу

  • 401: ключ отсутствует, неверного формата или не соответствует сайту либо шлюзу. Проверьте Authorization: Bearer и Base URL.
  • 404: неверный путь или лишний/пропущенный /v1 в Base URL. OpenAI-совместимый адрес заканчивается на /v1, затем добавляется /chat/completions.
  • model not found или model_not_found: опечатка в имени, неверный регистр или у аккаунта нет прав на модель. Копируйте имя из документации или страницы цен.
  • 400: выход параметра за границы, например temperature вне диапазона, thinking: disabled для M3.1-Flash или неподдерживаемое значение reasoning_effort.
  • finish_reason: "length" при пустом содержимом: лимит вывода слишком мал, токены рассуждения израсходовали бюджет. Увеличьте max_completion_tokens.
  • 429: сработал лимит. Официальная документация приводит ориентир: серия M3 — 200 RPM и 10 000 000 TPM, M2.x — 500 RPM и 20 000 000 TPM; фактически ориентируйтесь на аккаунт и консоль. Снижайте параллельность, добавляйте backoff.
  • 5xx или таймаут: колебания вышестоящего сервиса или сеть. Настройте таймауты, экспоненциальный backoff и резервную модель, не повторяйте бесконечно.

Цифры лимитов — лишь ориентир из документации на октябрь 2026 года; для разных аккаунтов, моделей и интерфейсов они могут отличаться. В production опирайтесь на консоль и фактические наблюдения, не выводите параллельность на максимум по цифрам из документации.

7. Чек-лист миграции

  1. Определите целевую платформу: официальный китайский сайт, официальный международный сайт или шлюз ZSQH. Ключ и Base URL должны быть с одной платформы.
  2. Измените base_url: для OpenAI-совместимого — /v1, для Anthropic-совместимого — /anthropic; не смешивайте.
  3. Измените имя модели: копируйте из официальной документации или цены на модели, следите за регистром, дефисами и версией.
  4. Измените параметры вывода: предпочтите max_completion_tokens и оставьте запас на токены рассуждения.
  5. Проверьте разбор стриминга: основной текст — delta.content, рассуждение — delta.reasoning_content; не предполагайте единственное поле.
  6. Проверьте вызов инструментов: используйте tools и возвращайте полное сообщение assistant с рассуждением, как требует документация.
  7. Добавьте таймауты, повторы и предохранитель: экспоненциальный backoff для 429 и 5xx, таймаут на запрос.
  8. Добавьте логи и мониторинг расхода: имя модели, длительность, входные и выходные токены, код ошибки; ключ в логи не пишите.
  9. Переключайте постепенно: сначала одну низкорисковую бизнес-функцию, сравните качество и стоимость, затем расширяйте трафик.
  10. Подготовьте откат: сохраните старую конфигурацию и старый ключ на время проверки, удаляйте после стабилизации.

Этот чек-лист подходит и для перехода с OpenAI на MiniMax, и для перехода с прямого подключения на шлюз. Суть миграции не в одной строке Base URL, а в совместной проверке аутентификации, моделей, параметров, разбора стриминга и мониторинга.

8. Прямое подключение или шлюз

Если вы используете только MiniMax, объём стабилен и можете напрямую пройти официальную регистрацию и расчёты, прямой путь самый короткий. Если нужны несколько моделей одновременно, единый счёт и единый ключ либо меньше конфигураций в китайской сети, шлюз удобнее.

При выборе шлюза подтвердите четыре вещи: какие модели MiniMax поддерживаются, совместим ли интерфейс с вашим (OpenAI или Anthropic), понятна ли тарификация, куда обращаться при сбоях. Сначала небольшой тест, затем production-трафик. Модели и тарификацию можно сверить на странице цены на модели, тестовый ключ создать на странице регистрации.

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

Какой Base URL у MiniMax API?

Для OpenAI-совместимого интерфейса международный сайт — https://api.minimax.io/v1, китайский — https://api.minimax.cn/v1. Anthropic-совместимые адреса — https://api.minimax.io/anthropic и https://api.minimax.cn/anthropic. Ориентируйтесь на сайт, где зарегистрированы.

Совместим ли MiniMax API с OpenAI SDK?

Совместимы основные чат-интерфейсы. Достаточно направить base_url на адрес MiniMax с /v1 и заменить имя модели на MiniMax. Но совместимость не означает полного совпадения: поля рассуждения, параметры токенов и детали вызова инструментов различаются.

Почему содержимое пустое, а finish_reason равен length?

Лимит вывода израсходован токенами рассуждения. Серия M3 включает рассуждение в бюджет вывода: сначала увеличьте max_completion_tokens, затем проверьте, не задан ли слишком низкий max_tokens.

Можно ли отключить рассуждение?

У MiniMax-M3.1-Flash рассуждение включено принудительно, передача thinking: disabled возвращает 400. Поддержка отключения у других моделей — по текущей официальной документации; для снижения задержки сначала уменьшайте reasoning_effort.

Что менять при миграции с OpenAI?

Как минимум ключ, Base URL, имя модели и параметры вывода; затем проверьте поля стриминга, вызов инструментов, таймауты, повторы и логи. Рекомендуется сначала выполнить нестриминговый curl, затем потоковый Python и только потом постепенное переключение.

10. Дальше

Выберите модель, пробейте нестриминговый запрос через curl, затем запустите стриминг на Python; убедившись, что content и reasoning_content разбираются корректно, подключайте бизнес. Если нужен единый вход, зарегистрируйтесь в ZSQH AI Gateway и сверьте доступные модели и тарификацию на странице цены на модели.

Полезное чтение: