RU ▾

API MiniMax на Python: используйте SDK OpenAI

Вам не нужен специальный клиент для вызова этого API из Python. Стандартный пакет openai работает после установки базового URL и ключа. Это руководство охватывает чат, потоковую передачу, JSON, инструменты, повторные попытки и расчет затрат.

Обновлено

Лента светящихся скобок кода, проходящая через слои API, символизирующая вызов API из Python

Ключевые моменты

  • Установите openai, затем передайте base_url https://api.minimaxapikey.com/v1 и ваш ключ в клиент.
  • Используйте идентификатор модели uncensored для чата, потоковой передачи, JSON-режима и вызова инструментов.
  • Обрабатывайте HTTP 429 с помощью backoff и ограничьте потоки 8 для полного ключа, 2 для пробного.
  • Читайте данные использования из каждого ответа и умножайте на $0,15 и $0,50 за 1 млн токенов для отслеживания расходов.

Установка и первый вызов

Для работы с MiniMax API на Python самый быстрый путь — использовать официальный пакет openai из PyPI. Сервис за этим сайтом — это размещенный API, совместимый с OpenAI, от независимого провайдера, поэтому отдельный SDK изучать не нужно. Это не платформа вендора, и единственные изменения по сравнению со стандартным скриптом OpenAI — это базовый URL, ключ и имя модели.

pip install --upgrade openai
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.minimaxapikey.com/v1",
    api_key=os.environ["UNCENSORED_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "Answer in plain English, briefly."},
        {"role": "user", "content": "What does a context window limit?"},
    ],
)
print(resp.choices[0].message.content)
print(resp.usage)

Получите ключ на странице ключа API. На новых аккаунтах можно активировать $0,50 пробного баланса в один клик, без карты, и он действителен в течение 7 дней. Храните ключ в переменной окружения, как показано, а не вставляйте его в файлы исходного кода.

Параметры сэмплирования и max_tokens

Обычные параметры передаются без изменений: temperature, top_p, stop, seed, а также штрафы за частоту и присутствие. Фиксированный seed с низкой температурой дает более воспроизводимые результаты для тестов, хотя не следует считать его гарантией идентичного текста.

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "List five verbs for a changelog."}],
    temperature=0.3,
    top_p=0.9,
    stop=["\n\n"],
    seed=42,
    max_tokens=120,
)

max_tokens необязателен. Без него завершение может использовать все оставшиеся токены из окна в 100 000 токенов после вашего промпта. Это полезно для длинных документов, но в производственном коде установите ограничение. Бесконтрольная генерация стоит реальных токенов вывода по $0,50 за 1 млн, а ограничение ставит предел ущербу от плохого промпта.

Потоковые ответы

Передайте stream=True и итерируйте. Ответ доставляется как серверные события (SSE), а SDK преобразует их в объекты чанков. Выводите текст дельты по мере поступления для чат-интерфейса с отзывчивым откликом.

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Write a short product description for a notebook."}],
    stream=True,
)

parts = []
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        piece = chunk.choices[0].delta.content
        parts.append(piece)
        print(piece, end="", flush=True)
print()
text = "".join(parts)

Данные использования отправляются в конце потока. Если версия вашего SDK предоставляет атрибут usage в последнем чанке, прочитайте его там; в противном случае подсчитывайте токены самостоятельно для контроля бюджета. Важный момент: потоковый запрос удерживает слот параллельных запросов до завершения потока. Если вы откроете восемь длинных потоков с полным ключом, девятый запрос получит ошибку 429 с кодом concurrency, пока один из них не завершится. Всегда закрывайте или полностью потребляйте поток, чтобы освободить слот.

JSON-режим для структурированного вывода

Когда нужен вывод, читаемый машиной, установите response_format в объект JSON. Упомяните JSON в промпте, а также опишите нужные ключи, так как флаг формата гарантирует корректный синтаксис JSON, но не вашу схему.

import json

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "Reply only with JSON using keys: title, tags (list of strings)."},
        {"role": "user", "content": "Summarise: a tutorial on caching HTTP responses in Python."},
    ],
    response_format={"type": "json_object"},
)

data = json.loads(resp.choices[0].message.content)
print(data["title"], data["tags"])

Все равно проверяйте результат. Убедитесь, что обязательные ключи существуют и имеют правильные типы, прежде чем использовать их, и решите, что делать вашему коду, если их нет, например, повторить попытку с более четкой инструкцией. Тонкий слой проверки, даже несколько проверок isinstance, экономит много времени на отладку в продакшене.

Вызов функций

Вызов инструментов следует формату OpenAI. Вы описываете функции в tools, при необходимости принуждаете к выбору с помощью tool_choice, и модель возвращает tool_calls с аргументами в формате JSON. Вы запускаете функцию и отправляете результат обратно как сообщение с role: "tool".

import json

def get_rate(currency):
    rates = {"EUR": 0.92, "GBP": 0.79}
    return json.dumps({"currency": currency, "per_usd": rates.get(currency)})

tools = [{
    "type": "function",
    "function": {
        "name": "get_rate",
        "description": "Exchange rate per 1 USD for a currency code.",
        "parameters": {
            "type": "object",
            "properties": {"currency": {"type": "string"}},
            "required": ["currency"],
        },
    },
}]

messages = [{"role": "user", "content": "How many EUR is 50 USD?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message
messages.append(msg)

for call in msg.tool_calls or []:
    args = json.loads(call.function.arguments)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": get_rate(args["currency"])})

final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)

Тарифы в этом примере вымышлены для демонстрации. В реальном коде функция вызывала бы ваш собственный сервис. Парсите аргументы с защитой с помощью json.loads внутри блока try, так как модель иногда может генерировать некорректные аргументы.

Лимиты запросов, повторные попытки и параллельная работа

Полный ключ позволяет 8 параллельных запросов и 300 в минуту; пробный ключ — 2 параллельных и 60 в минуту. Превышение возвращает HTTP 429. Код ошибки rate_limited для лимита в минуту и concurrency для одновременных запросов. Временная перегрузка также даёт 429 с заголовком Retry-After: 5. SDK OpenAI сам обрабатывает некоторые сбои, и вы можете увеличить это значение с помощью max_retries. Для пакетных задач добавьте собственный лимит потоков, чтобы оставаться в пределах лимита по конструкции, а не за счёт повторных попыток.

from concurrent.futures import ThreadPoolExecutor
from openai import OpenAI, RateLimitError
import os, time

client = OpenAI(
    base_url="https://api.minimaxapikey.com/v1",
    api_key=os.environ["UNCENSORED_KEY"],
    max_retries=2,
)

def ask(prompt):
    for attempt in range(4):
        try:
            r = client.chat.completions.create(
                model="uncensored",
                messages=[{"role": "user", "content": prompt}],
                max_tokens=200,
            )
            return r.choices[0].message.content
        except RateLimitError:
            time.sleep(5 * (attempt + 1))
    return None

prompts = [f"Write one tagline for product {i}." for i in range(20)]
with ThreadPoolExecutor(max_workers=8) as pool:
    results = list(pool.map(ask, prompts))

Используйте max_workers=2 для пробного ключа. Асинхронный клиент AsyncOpenAI принимает те же аргументы; используйте его с asyncio.Semaphore(8), чтобы обеспечить тот же потолок. В документации приведён список заголовков ответа, которые можно проверить на лимиты.

Сохранение истории разговора

API не имеет состояния. Он не запоминает предыдущий вызов, поэтому многооборотный чат работает за счёт отправки всей переписки каждый раз. Ведите список сообщений, добавляйте реплику пользователя, вызывайте API, затем добавляйте ответ ассистента перед следующим раундом.

history = [{"role": "system", "content": "You are a patient Python tutor."}]

def chat(user_text):
    history.append({"role": "user", "content": user_text})
    r = client.chat.completions.create(model="uncensored", messages=history)
    reply = r.choices[0].message.content
    history.append({"role": "assistant", "content": reply})
    return reply

print(chat("What is a list comprehension?"))
print(chat("Show me one with a filter."))

Этот паттерн имеет стоимость, которая растёт с каждым шагом: каждый запрос оплачивает все предыдущие шаги снова как входные токены. При окне в 100 000 токенов у вас много места, но длинные сессии становятся дорогими и медленными. Простая политика — сохранять системное сообщение и последние N шагов, или просить модель сделать краткое резюме старых шагов и заменить им старые шаги. Определите политику заранее, потому что внедрение обрезки в приложение чата сложнее, чем сразу заложить её с самого начала.

Обработка ошибок, кроме 429

SDK вызывает типизированные исключения, и их сортировка стоит нескольких строк. Ошибки аутентификации и плохие запросы не исправятся повторной попыткой, тогда как ошибки сети и перегрузка обычно исправляются. Обрабатывайте их по-разному.

import openai

try:
    r = client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "user", "content": "Hello"}],
        timeout=60,
    )
except openai.AuthenticationError:
    print("Check the API key and the Bearer header.")
except openai.RateLimitError as e:
    print("Slow down:", e.response.headers.get("Retry-After"))
except openai.APIConnectionError:
    print("Network problem, retry with backoff.")
except openai.APIStatusError as e:
    print("Server said", e.status_code, e.response.headers.get("X-Request-Id"))

При обращении в поддержку включите значение X-Request-Id из неудачного вызова. Он идентифицирует этот конкретный запрос. Установите явный timeout, как показано, так как по умолчанию он большой, и зависший вызов, удерживающий слот параллелизма, тихо снижает вашу пропускную способность. Неудачные или отклонённые запросы не оплачиваются, поэтому повторная попытка неудачного вызова не удваивает счёт.

Небольшая структура проекта, масштабируемая

Скрипты превращаются в сервисы. Небольшая структура в начале держит детали API в одном месте, так что последующее изменение имени модели, тайм-аута или лимитов затрагивает один файл вместо двадцати.

# llm.py
import os
from openai import OpenAI

BASE_URL = "https://api.minimaxapikey.com/v1"
MODEL = "uncensored"

_client = OpenAI(base_url=BASE_URL, api_key=os.environ["UNCENSORED_KEY"], timeout=60, max_retries=2)

def complete(messages, **kwargs):
    r = _client.chat.completions.create(model=MODEL, messages=messages, **kwargs)
    return r.choices[0].message.content, r.usage

Любой другой модуль импортирует complete и никогда не создаёт клиента. Эта единственная точка расширения — то место, куда позже можно добавить логирование, счётчик расходов или семафор. Если вам нужно больше справочных материалов, страница документации показывает те же эндпоинты в виде curl-команд, что удобно для сравнения падающего вызова Python с заведомо рабочим запросом.

Фиксация версий тоже помогает. Зафиксируйте пакет openai в файле requirements и обновляйте его целенаправленно, сначала прочитав заметки к выпуску, так как изменения SDK могут изменить имена исключений или поведение повторных попыток по умолчанию. Добавьте краткую заметку в README, указывающую, какой базовый URL и ID модели ожидает проект, чтобы новый коллега мог запустить его с первого дня без вопросов.

И последний момент по тестированию. Напишите хотя бы один тест, который запускается с фейковым клиентом, чтобы ваш набор тестов не тратил кредиты или не зависел от сети. Оставьте один живой дымовой тест, запускаемый вручную или в ночной задаче, чтобы рано ловить изменения в реальном API.

Отслеживание баланса и затрат в коде

Каждый ответ содержит заголовок X-Balance-USD, и SDK позволяет читать заголовки через with_raw_response. Логирование этого значения после каждого вызова — дешёвый способ поймать исчерпание баланса до того, как это сделают ваши пользователи.

raw = client.chat.completions.with_raw_response.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Say hello in French."}],
)
print("balance:", raw.headers.get("X-Balance-USD"))
print("request id:", raw.headers.get("X-Request-Id"))
resp = raw.parse()

def cost_usd(usage):
    return usage.prompt_tokens * 0.15 / 1_000_000 + usage.completion_tokens * 0.50 / 1_000_000

print(cost_usd(resp.usage))

Пример расчёта формулы: вызов с 2 000 входными токенами и 500 выходными токенами стоит 2 000 x 0,15 / 1 000 000 = $0,0003 за вход, плюс 500 x 0,50 / 1 000 000 = $0,00025 за выход, итого $0,00055. Тысяча таких вызовов обходится в $0,55. Неудачные или отклонённые запросы не оплачиваются, поэтому журнал, построенный на основе объектов успешного использования, будет точно соответствовать счёту.

Биллинг — оплата по факту с предоплаченного баланса без подписки. Пополнения от $20 до $500 любой целой суммой, с бонусами от $50, и кредит не сгорает; подробности на странице тарифов. Промпты не используются для обучения.

Вопросы и ответы

Есть ли отдельный пакет MiniMax для Python?

Вам не нужен отдельный пакет. Этот сервис совместим с OpenAI, поэтому стандартный пакет openai работает с настраиваемым base_url. Это независимый сервис, а не официальный SDK вендора.

Работает ли асинхронный клиент?

Да. AsyncOpenAI принимает те же аргументы base_url и api_key. Держите количество активных запросов на уровне вашего лимита параллельных запросов или ниже.

Как получить подсчёт токенов?

Каждый непотоковый ответ содержит объект usage с полями prompt_tokens и completion_tokens. Для потоков данные usage отправляются в конце, поэтому прочитайте их из последнего чанка, если ваш клиент предоставляет к ним доступ.

Какую длину контекста я могу использовать?

Контекстное окно составляет 100 000 токенов, которые делятся между промптом и завершением. max_tokens необязателен.

До вашего ключа — всего одна форма

Создайте аккаунт, скопируйте ключ, измените базовый URL. Это вся настройка.

Получить API-ключ