繁中 ▾

MiniMax API Python:使用 OpenAI SDK

你不需要特殊的客戶端即可從 Python 呼叫此 API。設定 base URL 和金鑰後,標準 openai 套件即可運作。本指南涵蓋聊天、串流輸出、JSON、工具、重試與成本計算。

更新

發光的程式碼括號編織穿過堆疊的 API 層,象徵 Python 呼叫 API

重點

  • 安裝 openai,然後將 base_url https://api.minimaxapikey.com/v1 與你的金鑰傳入客戶端。
  • 使用模型 ID uncensored 進行聊天、串流輸出、JSON 模式與函式呼叫。
  • 處理 HTTP 429 並使用退避演算法,完整金鑰將執行緒上限設為 8,試用金鑰設為 2。
  • 從每個回應讀取用量,並乘以每 1M token $0.15 與 $0.50 以追蹤支出。

安裝並進行首次呼叫

若要進行 minimax api python 開發,最快速的方法是從 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,以及頻率與存在懲罰。設定固定的 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 token $0.50,而上限能限制壞提示詞造成的損失。

串流回應

傳遞 stream=True 並進行迭代。回應以伺服器發送事件(SSE)形式交付,SDK 會將其轉換為 chunk 物件。在聊天介面中即時列印增量文字,以提供即時回應感。

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,以便新隊友第一天即可運行而無需詢問。

關於測試的最後一點。撰寫至少一個使用模擬客戶端執行的測試,以便測試套件不會消耗額度或依賴網路。保留一個手動執行或每晚執行的單一即時冒煙測試 (smoke test),以便及早發現真實 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。失敗或拒絕的請求不會收費,因此由成功 usage 物件建立的日誌將與帳單高度吻合。

計費方式為預付額度按量付費,無訂閱制。儲值金額範圍為 $20 至 $500,可任意整數金額儲值,儲值金額達 $50 以上即可獲得獎金,且額度永不過期;詳細資訊請見 定價頁面。提示詞不會用於模型訓練。

問答

MiniMax 有獨立的 Python 套件嗎?

這裡不需要。此服務與 OpenAI 相容,因此一般 openai 套件搭配自訂 base_url 即可運作。這是獨立服務,並非廠商的官方 SDK。

非同步客戶端運作正常嗎?

可以。AsyncOpenAI 接受相同的 base_url 和 api_key 參數。請將進行中的請求數量保持在並行限制以下。

如何取得 token 計數?

每個非串流回應都包含 usage 物件,內含 prompt_tokens 與 completion_tokens。對於串流,usage 會在結尾發送,因此請從最終 chunk 讀取(若你的客戶端提供此功能)。

我可以使用多長的上下文?

上下文視窗為 100,000 token,提示詞與補全共用。max_tokens 為選填。

只差一張表單,即可取得金鑰

建立帳號、複製金鑰、更改基礎 URL。這就是整個設定過程。

取得 API 金鑰