Python에서 MiniMax API 사용하기: OpenAI SDK 활용
Python에서 이 API를 호출하려면 특별한 클라이언트가 필요 없습니다. base URL과 키를 설정하면 표준 openai 패키지가 작동합니다. 이 가이드는 채팅, 스트리밍, JSON, 도구, 재시도 및 비용 계산을 다룹니다.
업데이트됨

주요 포인트
- openai를 설치한 후 base_url https://api.minimaxapikey.com/v1과 키를 클라이언트에 전달하세요.
- 채팅, 스트리밍, JSON 모드 및 함수 호출에는 모델 ID uncensored를 사용하세요.
- HTTP 429를 백오프로 처리하고 전체 키는 스레드를 8개, 체험 키는 2개로 제한하세요.
- 각 응답에서 사용량을 읽고 토큰 100만 개당 $0.15 및 $0.50에 곱해 지출을 추적하세요.
설치 및 첫 번째 호출
minimax api python에서 사용하려면 PyPI의 공식 openai 패키지가 가장 빠른 방법입니다. 이 사이트의 서비스는 독립된 공급자가 운영하는 호스팅된 OpenAI 호환 API이므로 별도의 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 키 페이지에서 키를 얻으세요. 새 계정은 카드 없이 클릭 한 번으로 7일 동안 유효한 $0.50의 체험 크레딧을 받을 수 있습니다. 소스 파일에 붙여넣는 대신 환경 변수에 키를 보관하세요.
샘플링 매개변수 및 max_tokens
일반적인 매개변수는 그대로 전달됩니다: temperature, top_p, stop, seed 및 frequency penalty와 presence penalty입니다. 낮은 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는 선택 사항입니다. 이를 지정하지 않으면 completion은 프롬프트 이후 남은 100,000 토큰 창을 모두 사용할 수 있습니다. 긴 문서에 유용하지만 프로덕션 코드에서는 제한을 설정하세요. 제어되지 않는 생성은 토큰 100만 개당 $0.50의 실제 출력 토큰 비용이 발생하며 제한은 나쁜 프롬프트로 인한 피해를 막아줍니다.
스트리밍 응답
stream=True를 전달하고 반복하세요. 응답은 서버 전송 이벤트로 전달되며 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 속성을 노출하는 경우 해당 위치에서 읽으세요. 그렇지 않으면 예산 관리를 위해 자체적으로 토큰을 세어야 합니다. 실용적인 참고 사항: 스트리밍된 요청은 스트림이 완료될 때까지 동시성 슬롯을 유지합니다. 전체 키에 8개의 긴 스트림을 열면 하나의 스트림이 완료될 때까지 9번째 요청은 concurrency 코드와 함께 429 오류를 받습니다. 슬롯이 해제되도록 스트림을 항상 닫거나 완전히 소비하세요.
구조화된 출력을 위한 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 체크 몇 개로 많은 디버깅을 줄일 수 있습니다.
함수 호출
함수 호출(tool calling)은 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."))
이 패턴은 대화마다 비용이 증가합니다: 각 요청은 이전 모든 대화를 입력 토큰으로 다시 지불해야 합니다. 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 세부 정보가 한 곳에 있으므로 모델 이름, 타임아웃 또는 제한의 변경이 20개 파일이 아닌 하나의 파일에 영향을 미칩니다.
# 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 변경은 예외 이름 또는 기본 재시도 동작을 변경할 수 있기 때문입니다. 프로젝트가 기대하는 base URL 및 모델 ID를 명시하는 짧은 README 노트와 함께 사용하면 새 팀원이 하루 만에 실행할 수 있습니다.
테스트에 대한 마지막 포인트. 가짜 클라이언트로 실행되는 테스트를 적어도 하나 작성하여 스위트가 크레딧을 소비하거나 네트워크에 의존하지 않도록 하세요. 실제 API의 변경 사항을 조기에 잡기 위해 수동 또는 야간 작업으로 실행되는 단일 라이브 smoke 테스트를 유지하세요.
코드에서 잔액 및 비용 추적
모든 응답에는 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입니다. 이러한 호출 1,000회는 $0.55가 됩니다. 실패하거나 거부된 요청은 요금이 부과되지 않으므로 성공적인 사용량 객체로 구성된 로그는 청구서와 거의 일치합니다.
청구 방식은 선불 크레딧을 사용한 종량제이며 구독이 없습니다. 충전 금액은 $20에서 $500까지 어떤 정수 금액으로든 가능하며, $50 이상부터 보너스가 제공되며 크레딧은 만료되지 않습니다. 자세한 내용은 가격 책정 페이지에서 확인할 수 있습니다. 프롬프트는 학습에 사용되지 않습니다.
더 많은 가이드
질문과 답변
별도의 MiniMax Python 패키지가 있나요?
별도가 필요 없습니다. 이 서비스는 OpenAI와 호환되므로 일반 openai 패키지가 custom base_url로 작동합니다. 벤더 공식 SDK가 아닌 독립 서비스입니다.
비동기 클라이언트는 작동하나요?
네. AsyncOpenAI는 동일한 base_url 및 api_key 인수를 받습니다. 진행 중인 요청 수를 동시성 제한 이하로 유지하세요.
토큰 개수는 어떻게 확인하나요?
스트리밍이 아닌 응답에는 prompt_tokens 및 completion_tokens가 포함된 usage 객체가 있습니다. 스트림의 경우 사용량은 마지막에 전송되므로 클라이언트가 노출하면 마지막 청크에서 읽으세요.
얼마나 긴 컨텍스트 창을 사용할 수 있나요?
창은 프롬프트와 completion 간에 공유되는 100,000 토큰입니다. max_tokens는 선택 사항입니다.
키는 양식 하나만 작성하면 받을 수 있습니다
계정을 생성하고 키를 복사한 후 기본 URL을 변경하세요. 설정은 이것으로 끝입니다.