MiniMax API Python:使用 OpenAI SDK
你不需要特殊的客户端即可从 Python 调用此 API。设置 base URL 和密钥后,标准的 openai 包即可使用。本指南涵盖聊天、流式输出、JSON、工具、重试和成本计算。
更新于

要点
- 安装 openai,然后将 base_url https://api.minimaxapikey.com/v1 和你的密钥传递给客户端。
- 使用模型 ID uncensored 进行聊天、流式输出、JSON 模式和工具调用。
- 处理 HTTP 429 错误并采用退避策略,完整密钥最多允许 8 个线程,试用密钥最多允许 2 个线程。
- 从每个响应中读取使用情况,并分别乘以每 1M token $0.15 和 $0.50 的单价以跟踪支出。
安装并进行首次调用
要在 Python 中使用 MiniMax API,最快的方式是使用来自 PyPI 的官方 openai 包。该网站背后的服务是由独立提供商托管的兼容 OpenAI 的 API,因此没有单独的 SDK 需要学习。它与标准 OpenAI 脚本的唯一区别在于 base 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,以及频率和存在惩罚。使用低 temperature 和固定 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 个 token 窗口中的剩余部分。这对长文档很有用,但在生产代码中应设置上限。失控的生成会消耗真实的输出 token,价格为每 1M $0.50,上限可以限制坏提示词造成的损害。
流式响应
传递 stream=True 并迭代。响应以服务器发送事件的形式交付,SDK 将其转换为 chunk 对象。随着 delta 文本的到达打印它们,让聊天界面响应更灵敏。
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 版本在最后一个 chunk 上暴露了 usage 属性,请在此处读取;否则,请在你的端侧计算 token 以进行预算。一个实际的问题是:流式请求会占用其并发槽位直到流结束。如果你在完整密钥上打开八个长流,第九个请求将获得 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 强制选择,模型返回带有 JSON 参数的 tool_calls。你运行函数并将结果作为带有 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)
此示例中的费率是为演示编造的。在实际代码中,函数会调用你自己的服务。在 try 块内使用 json.loads 防御性地解析参数,因为模型偶尔会发出格式错误的参数。
速率限制、重试和并行工作
完整密钥允许 8 个并发请求和每分钟 300 次请求;试用密钥允许 2 个并发请求和每分钟 60 次请求。超出限制将返回 HTTP 429 错误。每分钟请求上限的错误代码为 rate_limited,并发调用过多的错误代码为 concurrency。临时过载也会返回 429 错误,并附带 Retry-After: 5 响应头。OpenAI SDK 会自动重试部分失败,你可以通过设置 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."))
这种模式随着每一轮对话而增加成本:每个请求都要为所有早期轮次作为输入 token 付费。在 100,000 token 的窗口下你有很大空间,但长会话会变得昂贵且缓慢。一个简单的策略是保留系统消息和最后 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 调用与已知良好的请求进行比较很有用。
版本锁定也有帮助。在 requirements 文件中锁定 openai 包并有目的地升级,先阅读发布说明,因为 SDK 更改可能会改变异常名称或默认重试行为。配合简短的 README 说明项目期望哪个 base 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 个输入 token 和 500 个输出 token,输入费用为 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 参数。保持并发请求数不超过你的并发限制。
如何获取 token 计数?
每个非流式响应都包含带有 prompt_tokens 和 completion_tokens 的 usage 对象。对于流式输出,usage 在末尾发送,因此如果客户端暴露了该对象,请从最后一个 chunk 中读取。
我可以使用多大的上下文长度?
上下文窗口为 100,000 个 token,由提示词和补全共享。max_tokens 是可选的。
只差一张表单,即可获得密钥
创建账户,复制密钥,更改基础 URL。这就是全部设置。