API MiniMax em Python: use o SDK OpenAI
Você não precisa de um cliente especial para chamar esta API em Python. O pacote openai padrão funciona assim que você define a base URL e a chave, e este guia cobre chat, streaming, JSON, ferramentas, retentativas e cálculo de custos.
Atualizado

Pontos principais
- Instale openai, depois passe base_url https://api.minimaxapikey.com/v1 e sua chave para o cliente.
- Use o ID do modelo uncensored para chat, streaming, modo JSON e chamada de ferramentas.
- Trate o HTTP 429 com backoff e limite as threads a 8 com uma chave completa e 2 com uma chave de teste.
- Leia o usage de cada resposta e multiplique por $0,15 e $0,50 por 1M de tokens para rastrear o gasto.
Instale e faça a primeira chamada
Para trabalhar com a MiniMax API em Python, a rota mais rápida é o pacote oficial openai do PyPI. O serviço por trás deste site é uma API hospedada e compatível com OpenAI executada por um provedor independente, então não há um SDK separado para aprender. Não é a plataforma do fornecedor, e as únicas alterações em um script OpenAI padrão são a base URL, a chave e o nome do modelo.
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)
Obtenha a chave na página chave de API. Contas novas podem resgatar $0,50 de crédito de teste grátis com um clique, sem necessidade de cartão, e ele permanece válido por 7 dias. Mantenha a chave em uma variável de ambiente, conforme mostrado, em vez de colá-la nos arquivos de código.
Parâmetros de amostragem e max_tokens
Os parâmetros habituais são passados: temperature, top_p, stop, seed, além das penalidades de frequência e presença. Um seed fixo com temperatura baixa oferece saídas mais repetíveis para testes, embora você não deva tratá-lo como garantia de texto idêntico.
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 é opcional. Sem ele, o completion pode usar o que sobrar da janela de 100.000 tokens após seu prompt. Isso é útil para documentos longos, mas defina um limite no código de produção. Uma geração descontrolada custa tokens de saída reais a $0,50 por 1M, e um limite coloca um teto no dano de um prompt ruim.
Respostas em streaming
Passe stream=True e itere. A resposta é entregue como eventos enviados pelo servidor, e o SDK os transforma em objetos chunk. Imprima o texto delta conforme chega para uma interface de chat que pareça responsiva.
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)
Os números de usage são enviados no final do stream. Se a versão do seu SDK expuser um atributo usage no último chunk, leia-o ali; caso contrário, conte tokens do seu lado para o orçamento. Um ponto prático: uma solicitação em streaming mantém seu slot de concorrência até que o stream termine. Se você abrir oito streams longos com uma chave completa, uma nona solicitação receberá um 429 com o código concurrency até que um termine. Sempre feche ou consuma totalmente um stream para liberar o slot.
Modo JSON para saída estruturada
Quando você precisa de saída legível por máquina, defina response_format para um objeto JSON. Mencione JSON no prompt também e descreva as chaves que deseja, porque o sinalizador de formato garante sintaxe JSON válida, mas não o seu esquema.
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"])
Ainda assim, valide o resultado. Verifique se as chaves obrigatórias existem e têm os tipos corretos antes de usá-las, e decida o que seu código faz quando elas não estão presentes, como tentar novamente uma vez com uma instrução mais clara. Uma camada de validação fina, mesmo com algumas verificações isinstance, economiza muito tempo de depuração em produção.
Chamada de funções
A chamada de funções segue o formato da OpenAI. Você descreve funções em tools, força opcionalmente uma escolha com tool_choice, e o modelo retorna tool_calls com argumentos JSON. Você executa a função e envia o resultado de volta como uma mensagem com 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)
As taxas neste exemplo são fictícias para a demonstração. No código real, a função chamaria seu próprio serviço. Analise os argumentos de forma defensiva com json.loads dentro de um bloco try, já que o modelo pode ocasionalmente emitir argumentos malformados.
Limites de taxa, retentativas e trabalho paralelo
Uma chave completa permite 8 requisições simultâneas e 300 por minuto; uma chave de teste permite 2 simultâneas e 60 por minuto. Ultrapassar os limites retorna HTTP 429. O código de erro é rate_limited para o limite por minuto e concurrency para muitas chamadas simultâneas. Sobrecarga temporária também gera 429, com o cabeçalho Retry-After: 5. O SDK da OpenAI tenta novamente alguns erros por conta própria, e você pode aumentar isso com max_retries. Para trabalhos em lote, adicione seu próprio limite de threads para permanecer abaixo do limite por design, em vez de depender de novas tentativas.
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))
Use max_workers=2 em uma chave de teste. O cliente assíncrono, AsyncOpenAI, aceita os mesmos argumentos; combine-o com um asyncio.Semaphore(8) para impor o mesmo teto. A documentação lista os cabeçalhos de resposta que você pode inspecionar para limites.
Mantendo o histórico de conversas
A API é stateless. Ela não lembra a chamada anterior, então um chat multi-turno funciona enviando toda a conversa a cada vez. Mantenha uma lista de mensagens, anexe o turno do usuário, chame a API, depois anexe a resposta do assistente antes da próxima rodada.
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."))
Este padrão tem um custo que cresce a cada turno: cada requisição paga por todos os turnos anteriores novamente como tokens de entrada. Com uma janela de 100.000 tokens, você tem bastante margem, mas sessões longas ficam caras e lentas. Uma política simples é manter a mensagem do sistema e os últimos N turnos, ou pedir ao modelo um resumo curto dos turnos mais antigos e substituí-los por ele. Defina uma política cedo, porque adaptar o corte a um aplicativo de chat é mais complicado do que implementá-lo desde o início.
Tratamento de erros além de 429
O SDK lança exceções tipadas, e classificá-las vale algumas linhas. Problemas de autenticação e solicitações inválidas não se corrigirão na retentativa, enquanto erros de rede e sobrecarga geralmente se corrigirão. Trate-os de forma diferente.
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"))
Ao entrar em contato com o suporte, inclua o valor de X-Request-Id da chamada com falha. Ele identifica exatamente essa requisição. Defina um timeout explícito, conforme mostrado, já que o padrão é longo, e uma chamada travada que ocupa um slot de concorrência reduz silenciosamente sua taxa de transferência. Requisições com falha ou recusadas não são cobradas, portanto, tentar novamente uma chamada com falha não dobra a conta.
Uma estrutura de projeto pequena que escala
Scripts crescem para serviços. Uma pequena estrutura no início mantém os detalhes da API em um lugar, para que uma alteração posterior no nome do modelo, no timeout ou nos limites toque um arquivo em vez de vinte.
# 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
Todos os outros módulos importam complete e nunca criam um cliente. Essa única junção é onde você adiciona logging, um contador de gastos ou um semáforo mais tarde. Se quiser mais material de referência, a página docs mostra os mesmos endpoints em forma de curl, o que é útil para comparar uma chamada Python com falha contra uma requisição conhecida como válida.
A fixação de versão também ajuda. Fixe o pacote openai no seu arquivo de requisitos e faça upgrade com propósito, lendo primeiro as notas de lançamento, porque mudanças no SDK podem alterar nomes de exceções ou comportamento padrão de nova tentativa. Combine isso com uma nota curta no README indicando qual URL base e ID de modelo o projeto espera, para que um novo colega possa executá-lo no primeiro dia sem precisar perguntar.
Um último ponto sobre testes. Escreva pelo menos um teste que execute contra um cliente falso, para que sua suíte não gaste crédito ou dependa da rede. Mantenha um único teste de fumaça ao vivo, executado manualmente ou em um trabalho noturno, para capturar alterações na API real cedo.
Rastreamento de saldo e custo no código
Cada resposta carrega X-Balance-USD, e o SDK permite ler cabeçalhos através de with_raw_response. Registrar isso após cada chamada é uma maneira barata de detectar um saldo esgotado antes que seus usuários percebam.
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))
Uma verificação prática da fórmula: uma chamada com 2.000 tokens de entrada e 500 tokens de saída custa 2.000 x 0,15 / 1.000.000 = $0,0003 para entrada, mais 500 x 0,50 / 1.000.000 = $0,00025 para saída, totalizando $0,00055. Mil chamadas assim totalizam $0,55. Requisições com falha ou recusadas não são cobradas, portanto, um log construído a partir de objetos de uso bem-sucedidos corresponderá à conta de perto.
A cobrança é pagamento por uso a partir de crédito pré-pago, sem assinatura. Recargas variam de $20 a $500 em qualquer valor inteiro, com bônus a partir de $50, e o crédito nunca expira; os detalhes estão na página de preços. Prompts não são usados para treinamento.
Mais guias
Perguntas e respostas
Existe um pacote Python separado para MiniMax?
Você não precisa de um aqui. Este serviço é compatível com OpenAI, então o pacote openai regular funciona com base_url personalizada. É um serviço independente, não o SDK oficial do fornecedor.
O cliente assíncrono funciona?
Sim. AsyncOpenAI aceita os mesmos argumentos base_url e api_key. Mantenha o número de requisições em andamento igual ou abaixo do seu limite de concorrência.
Como obter contagens de tokens?
Cada resposta sem streaming tem um objeto de uso com prompt_tokens e completion_tokens. Para streams, o uso é enviado no final, então leia-o do último chunk se seu cliente o expuser.
Qual comprimento de contexto posso usar?
A janela é de 100.000 tokens, compartilhada entre prompt e conclusão. max_tokens é opcional.
Sua chave está a um formulário de distância
Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.