ES ▾

API MiniMax en Python: usa el SDK de OpenAI

No necesitas un cliente especial para llamar a esta API desde Python. El paquete openai estándar funciona una vez que configuras la base URL y la clave, y esta guía cubre chat, streaming, JSON, herramientas, reintentos y cálculo de costos.

Actualizado

Una cinta de corchetes de código brillantes que se entrelazan a través de capas de API apiladas, representando Python llamando a una API

Puntos clave

  • Instala openai, luego pasa base_url https://api.minimaxapikey.com/v1 y tu clave al cliente.
  • Usa el ID de modelo uncensored para chat, streaming, modo JSON y llamadas a funciones.
  • Maneja el HTTP 429 con retroceso exponencial y limita los hilos a 8 para una clave completa, 2 para una clave de prueba.
  • Lee el uso de cada respuesta y multiplica por $0.15 y $0.50 por 1M de tokens para rastrear el gasto.

Instala y haz la primera llamada

Para usar minimax api python, la vía más rápida es el paquete oficial openai de PyPI. El servicio detrás de este sitio es una API compatible con OpenAI alojada por un proveedor independiente, así que no hay un SDK separado que aprender. No es la plataforma del proveedor, y los únicos cambios respecto a un script de OpenAI estándar son la URL base, la clave y el nombre del 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)

Obtén la clave en la página de clave de API. Las cuentas nuevas pueden reclamar $0.50 de crédito de prueba con un solo clic, sin necesidad de tarjeta, y este crédito es válido durante 7 días. Guarda la clave en una variable de entorno como se muestra, en lugar de pegarla en los archivos de código.

Parámetros de muestreo y max_tokens

Los parámetros habituales se pasan directamente: temperature, top_p, stop, seed, y las penalizaciones de frecuencia y presencia. Un seed fijo con una temperatura baja te proporciona resultados más reproducibles para las pruebas, aunque no debes considerarlo una garantía 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 es opcional. Sin él, el completado puede usar lo que quede de la ventana de 100.000 tokens después de tu prompt. Esto es útil para documentos largos, pero establece un límite en el código de producción. Una generación descontrolada consume tokens de salida reales a $0.50 por 1M, y un límite pone un tope al daño de un prompt defectuoso.

Respuestas en streaming

Pasa stream=True e itera. La respuesta se entrega como eventos enviados por el servidor, y el SDK los convierte en objetos fragmento. Imprime el texto delta a medida que llega para una interfaz de chat que se sienta receptiva.

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)

Los datos de uso se envían al final del streaming. Si la versión de tu SDK expone un atributo usage en el último fragmento, léelo allí; de lo contrario, cuenta los tokens en tu lado para la gestión del presupuesto. Un punto práctico: una petición en streaming mantiene su ranura de concurrencia hasta que finalice el streaming. Si abres ocho streams largos con una clave completa, una novena petición recibirá un 429 con el código concurrency hasta que una de ellas se complete. Cierra o consume completamente un stream para liberar la ranura.

Modo JSON para salida estructurada

Cuando necesites una salida legible por máquina, establece response_format a un objeto JSON. Menciona JSON en el prompt también, y describe las claves que quieres, porque la bandera de formato garantiza sintaxis JSON válida pero no tu 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"])

Aún así, valida el resultado. Verifica que las claves requeridas existan y tengan los tipos correctos antes de usarlas, y decide qué hace tu código cuando no las tienen, como reintentar una vez con una instrucción más clara. Una capa de validación ligera, incluso unas pocas comprobaciones isinstance, ahorra mucha depuración en producción.

Llamadas a funciones

Las llamadas a funciones siguen la forma de OpenAI. Describes funciones en tools, fuerzas opcionalmente una elección con tool_choice, y el modelo devuelve tool_calls con argumentos JSON. Ejecutas la función y envías el resultado de vuelta como un mensaje con 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)

Las tarifas en este ejemplo son ficticias para la demostración. En el código real, la función llamaría a tu propio servicio. Analiza los argumentos de forma defensiva con json.loads dentro de un bloque try, ya que un modelo puede ocasionalmente emitir argumentos mal formados.

Límites de peticiones, reintentos y trabajo paralelo

Una clave completa permite 8 peticiones simultáneas y 300 por minuto; una clave de prueba permite 2 simultáneas y 60 por minuto. Superar estos límites devuelve HTTP 429. El código de error es rate_limited para el límite por minuto y concurrency para demasiadas llamadas simultáneas. Una sobrecarga temporal también devuelve un 429, con la cabecera Retry-After: 5. El SDK de OpenAI reintenta algunos errores por sí mismo, y puedes aumentar este valor con max_retries. Para trabajos por lotes, añade tu propio límite de hilos para mantenerte por debajo del límite por diseño, en lugar de depender de los reintentos.

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))

Usa max_workers=2 con una clave de prueba. El cliente asíncrono, AsyncOpenAI, acepta los mismos argumentos; combínalo con un asyncio.Semaphore(8) para imponer el mismo tope. La documentación enumera los encabezados de respuesta que puedes inspeccionar para ver los límites.

Mantener el historial de conversación

La API es sin estado. No recuerda la llamada anterior, por lo que un chat de múltiples turnos funciona enviando toda la conversación cada vez. Mantén una lista de mensajes, añade el turno del usuario, llama a la API, luego añade la respuesta del asistente antes de la siguiente ronda.

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 patrón tiene un costo que crece con cada turno: cada petición paga por todos los turnos anteriores nuevamente como tokens de entrada. Con una ventana de 100.000 tokens tienes mucho espacio, pero las sesiones largas se vuelven caras y lentas. Una política simple es mantener el mensaje del sistema y los últimos N turnos, o pedirle al modelo un resumen corto de turnos anteriores y reemplazarlos con él. Decide una política temprano, porque agregar recorte a una aplicación de chat es más incómodo que construirlo desde el inicio.

Manejo de errores más allá de 429

El SDK lanza excepciones tipadas, y ordenarlas vale unas pocas líneas. Los problemas de autenticación y las malas solicitudes no se arreglarán con un reintento, mientras que los errores de red y la sobrecarga generalmente sí. Trátalos de manera 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"))

Cuando contactes con soporte, incluye el valor de X-Request-Id de la llamada fallida. Este identifica esa petición exacta. Establece un timeout explícito como se muestra, ya que el valor por defecto es largo, y una llamada bloqueada que mantiene una ranura de concurrencia reduce silenciosamente tu capacidad de procesamiento. Las peticiones fallidas o rechazadas no se cobran, por lo que reintentar una llamada fallida no duplica la factura.

Una estructura de proyecto pequeña que escala

Los scripts crecen hasta convertirse en servicios. Un poco de estructura al principio mantiene los detalles de la API en un solo lugar, para que un cambio posterior en el nombre del modelo, el tiempo de espera o los límites toque un archivo en lugar de veinte.

# 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

Cada otro módulo importa complete y nunca construye un cliente. Esa única unión es donde agregas registro, un contador de gasto o un semáforo más tarde. Si quieres más material de referencia, la página de documentación muestra los mismos endpoints en forma de curl, lo cual es útil para comparar una llamada Python fallida contra una petición conocida como correcta.

El bloqueo de versión también ayuda. Fija el paquete openai en tu archivo de requisitos y actualízalo de forma intencionada, leyendo primero las notas de la versión, porque los cambios en el SDK pueden alterar los nombres de las excepciones o el comportamiento de reintento por defecto. Acompáñalo con una nota breve en el README indicando qué base URL y model ID espera el proyecto, para que un nuevo compañero pueda ejecutarlo desde el primer día sin preguntar.

Un último punto sobre las pruebas. Escribe al menos una prueba que se ejecute contra un cliente falso, para que tu suite no gaste crédito ni dependa de la red. Mantén una única prueba de humo en vivo, ejecutada manualmente o en un trabajo nocturno, para detectar cambios en la API real temprano.

Rastreo de saldo y costo en el código

Cada respuesta lleva X-Balance-USD, y el SDK te permite leer encabezados a través de with_raw_response. Registrarlo después de cada llamada es una forma barata de detectar un saldo agotado antes que tus usuarios.

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))

Una comprobación práctica de la fórmula: una llamada con 2.000 tokens de entrada y 500 de salida cuesta 2.000 x 0.15 / 1.000.000 = $0.0003 para entrada, más 500 x 0.50 / 1.000.000 = $0.00025 para salida, es decir, $0.00055. Mil llamadas de este tipo suman $0.55. Las peticiones fallidas o rechazadas no se cobran, así que un registro basado en objetos de uso exitosos coincidirá estrechamente con la factura.

La facturación es de pago por uso desde crédito prepago sin suscripción. Las recargas van de $20 a $500 en cualquier cantidad entera, con bonificaciones desde $50, y el crédito no caduca; los detalles están en la página de precios. Los prompts no se usan para entrenamiento.

Preguntas y respuestas

¿Existe un paquete de Python separado para MiniMax?

No necesitas uno aquí. Este servicio es compatible con OpenAI, por lo que el paquete openai regular funciona con una base_url personalizada. Es un servicio independiente, no el SDK oficial del proveedor.

¿Funciona el cliente asíncrono?

Sí. AsyncOpenAI acepta los mismos argumentos base_url y api_key. Mantén el número de peticiones en curso por debajo o igual a tu límite de concurrencia.

¿Cómo obtengo los recuentos de tokens?

Cada respuesta sin streaming tiene un objeto usage con prompt_tokens y completion_tokens. Para streams, el usage se envía al final, así que léelo del último chunk si tu cliente lo expone.

¿Qué longitud de contexto puedo usar?

La ventana es de 100.000 tokens, compartida entre prompt y completion. max_tokens es opcional.

Tu clave está a un formulario de distancia

Crea una cuenta, copia la clave, cambia la URL base. Esa es toda la configuración.

Obtener clave de API