MiniMax M3는 최대 1,000,000 토큰의 컨텍스트 창을 가진 최첨단 추론 및 코딩 모델입니다. 이 숫자가 핵심입니다. 전체 리포지토리, 일주일치 로그 또는 긴 설계 문서를 한 번의 호출로 입력하고 모든 것을 통해 추론하도록 요청할 수 있습니다. 이 모델이 무엇이며 어디에 적합한지에 대한 배경 지식을 원하시면 먼저 MiniMax M3란 무엇인가를 읽어보세요.
이 가이드는 실습 버전입니다. API 키를 얻고, 세 가지 방법으로 첫 번째 요청을 보내고, 모든 단계를 Apidog에서 테스트하여 코드를 연결하기 전에 원시 요청과 응답을 확인할 수 있습니다. 따라하고 싶다면 Apidog를 다운로드하세요.
공식 참조 자료는 MiniMax API 문서에 있습니다. 탭에 열어두세요.
필요한 것
- platform.minimax.io의 MiniMax 계정.
- API 키 (아래에서 생성합니다).
- 사용량 지불 방법: 종량제 크레딧 또는 구독 토큰 플랜. 둘 다 동일한 엔드포인트에서 작동합니다.
curl 예제를 위해서는 다른 것을 설치할 필요가 없습니다. SDK 예제를 위해서는 Python 3.8+ 또는 Node 18+가 필요합니다.
1단계: API 키 얻기
platform.minimax.io에 로그인하고, 계정의 API 키 섹션을 열어 새 키를 생성하세요. MiniMax는 두 가지 종류의 자격 증명을 발급하며, 그 차이가 중요합니다.
- 일반 API 키는 종량제 잔액에 대해 요금이 청구됩니다.
- 구독 키는 플랜(Plus, Max, Ultra)의 토큰 크레딧을 사용합니다. 플랜의 토큰이 소진되면, 플랜이 갱신되거나 종량제 키로 전환할 때까지 해당 키를 통한 호출은 중단됩니다.
청구 방식에 맞는 것을 선택하세요. 키를 한 번 복사하여 저장하세요. 다시 볼 수 없습니다.
키를 소스 코드에 직접 붙여넣지 마세요. 대신 환경 변수로 내보내세요.
export MINIMAX_API_KEY="your-key-here"
이렇게 하면 비밀이 Git 기록 및 공유할 수 있는 모든 파일에서 제외됩니다. 편집기 내에서 API 키를 사용하는 경우에도 동일한 위생 규칙이 적용됩니다. 우리는 VS Code 확장 API 키 보안에서 일반적인 유출 사례를 다뤘습니다.
2단계: 첫 번째 요청 보내기
기본 URL은 https://api.minimax.io/v1이며, 채팅은 POST https://api.minimax.io/v1/chat/completions에 있습니다. 인증은 베어러 토큰: Authorization: Bearer $MINIMAX_API_KEY입니다. 모델 ID 문자열은 MiniMax-M3입니다.
다음은 curl을 사용한 가장 작은 유용한 호출입니다. 모델에게 함수를 비동기식으로 리팩토링하도록 요청하는 실제 작업입니다.
curl https://api.minimax.io/v1/chat/completions \
-H "Authorization: Bearer $MINIMAX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"MiniMax-M3","messages":[{"role":"user","content":"Refactor this function to be async."}]}'
M3를 호출하는 세 가지 방법이 있습니다. MiniMax는 Anthropic SDK를 권장하지만, OpenAI SDK와 원시 HTTP 모두 동일한 엔드포인트에서 작동합니다. 스택에서 이미 사용하는 방식을 사용하세요.
다음은 Python의 OpenAI SDK입니다. 일반적인 OpenAI 설정과 유일한 변경점은 base_url입니다.
from openai import OpenAI
client = OpenAI(
base_url="https://api.minimax.io/v1",
api_key="YOUR_API_KEY",
)
response = client.chat.completions.create(
model="MiniMax-M3",
messages=[
{"role": "user", "content": "Refactor this function to be async."}
],
)
print(response.choices[0].message.content)
Node에서도 동일한 아이디어로, 다시 기본 URL만 변경합니다.
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.minimax.io/v1",
apiKey: process.env.MINIMAX_API_KEY,
});
const response = await client.chat.completions.create({
model: "MiniMax-M3",
messages: [
{ role: "user", content: "Refactor this function to be async." },
],
});
console.log(response.choices[0].message.content);
Qwen 3.7 API를 사용해 보셨다면 이 패턴이 익숙할 것입니다. 대부분의 최첨단 모델은 이제 OpenAI 호환 인터페이스를 노출하므로 마이그레이션 비용은 한 줄에 불과합니다. OpenAI Python SDK 문서 및 Anthropic SDK 문서에서 전체 클라이언트 옵션을 다룹니다.
3단계: Apidog에서 테스트하고 검사하기
이 호출을 애플리케이션 내부에 숨기기 전에, 수동으로 보내고 원시 응답을 읽어보세요. 이것이 바로 Apidog가 순환 과정에서 제 역할을 하는 곳입니다.
- 새 HTTP 요청을 생성하고, URL
https://api.minimax.io/v1/chat/completions와 함께 메서드를POST로 설정합니다. - 환경 패널을 열고, 키를 값으로 하는
MINIMAX_API_KEY라는 변수를 추가합니다. 요청 본문이나 공유 컬렉션에 절대 노출되지 않도록 환경 변수로 저장합니다. - 요청 헤더에
Authorization을 값Bearer {{MINIMAX_API_KEY}}와 함께 추가합니다. Apidog는 전송 시 변수를 대체합니다. - 본문을 원시 JSON으로 설정하고 curl 예제의 동일한 페이로드를 붙여넣습니다.
- 보내기(Send)를 누르고 응답 패널을 확인합니다.
[스크린샷: Apidog의 MiniMax-M3 요청 및 응답]
토큰을 환경 변수로 저장하면 비밀을 유출하지 않고 팀원들과 요청을 공유할 수 있으며, 하나의 변수를 변경하여 키(종량제 대 구독)를 교체할 수 있습니다. 나중에 스트리밍을 켜면 Apidog는 서버 전송 이벤트를 도착하는 대로 보여주므로, 파싱 코드를 작성하기 전에 스트림 형식을 확인할 수 있습니다. 응답을 수동으로 검사하면 스키마의 예상치 못한 부분을 일찍 발견할 수 있는데, 이는 엔드포인트를 신뢰하기 전에 테스트하는 전체 목적입니다.
4단계: 사고(思考) 기능 켜고 끄기
M3는 추론 모델입니다. 기본적으로 최종 답변을 반환합니다. 중간 추론을 노출하도록 요청할 수도 있는데, 이는 모델이 왜 특정 결론에 도달했는지 디버깅하거나 추론을 검토 단계에 활용할 때 유용합니다.
OpenAI SDK를 사용하면 extra_body를 통해 reasoning_split을 전달합니다.
from openai import OpenAI
client = OpenAI(
base_url="https://api.minimax.io/v1",
api_key="YOUR_API_KEY",
)
response = client.chat.completions.create(
model="MiniMax-M3",
messages=[
{"role": "user", "content": "Refactor this function to be async."}
],
extra_body={"reasoning_split": True},
)
print(response.choices[0].message.reasoning_details[0]["text"]) # the thinking
print(response.choices[0].message.content) # the final answer
reasoning_split이 켜져 있으면, 사고(thinking) 텍스트는 response.choices[0].message.reasoning_details[0]["text"]에서 반환되고 최종 답변은 response.choices[0].message.content에 유지됩니다. UI에서 이 두 가지를 분리하세요. 사용자에게는 답변을 보여주고, 추론은 로그나 검증 통과를 위해 보관하세요.
다단계 리팩토링, 까다로운 버그 추적, 체인을 감사하고 싶은 모든 것과 같은 어려운 문제에 대해서는 사고 기능을 켜세요. 추가적인 추론 토큰이 불필요한 시간과 비용을 발생시키는 단순하고 지연 시간에 민감한 호출에 대해서는 끄세요.
5단계: 1M 토큰 컨텍스트 활용하기
큰 컨텍스트 창은 M3를 선택해야 하는 이유입니다. 전체 로그 파일을 붙여넣고 모든 내용에 대해 단 하나의 질문을 할 수 있습니다.
with open("production-2026-05-30.log") as f:
log_text = f.read()
response = client.chat.completions.create(
model="MiniMax-M3",
messages=[
{
"role": "user",
"content": f"Find the root cause of the 502 spike at 14:20 UTC.\n\n{log_text}",
}
],
)
알아야 할 과금 관련 정보입니다. MiniMax는 512K 입력 토큰 이하의 호출에 대해서는 표준 요금을 청구하며, 입력이 512K 토큰을 초과하면 더 높은 장문 컨텍스트 요금이 적용됩니다. 따라서 400K 토큰 프롬프트에서 600K 토큰 프롬프트로의 점프는 선형적이지 않습니다. 이는 가격 임계값을 넘습니다.
실질적인 교훈: 습관적으로 수백만 개의 토큰을 컨텍스트에 쏟아붓지 마세요. 모델에 필요한 부분만 보내세요. 에이전트에서 여러 호출을 연결하는 경우, 호출당 컨텍스트를 줄이는 것이 요금을 절감할 수 있는 가장 큰 지렛대 중 하나입니다. 이에 대해서는 에이전트 토큰 비용 절감 방법에서 더 자세히 다룹니다.
6단계: 도구 호출 및 멀티모달 입력
M3는 도구 호출과 멀티모달 입력을 처리하므로, 텍스트뿐만 아니라 에이전트를 구동하고 이미지를 읽을 수 있습니다.
도구 호출의 경우, 모델이 호출할 수 있는 도구를 선언한 다음 모델이 반환하는 호출을 처리합니다.
tools = [
{
"type": "function",
"function": {
"name": "run_tests",
"description": "Run the test suite for a given module path.",
"parameters": {
"type": "object",
"properties": {
"module": {"type": "string"},
},
"required": ["module"],
},
}
]
response = client.chat.completions.create(
model="MiniMax-M3",
messages=[
{"role": "user", "content": "Fix the failing test in auth/session.py and confirm it passes."}
],
tools=tools,
)
모델이 도구를 호출하기로 결정하면 응답에는 tool_calls 배열이 포함됩니다. 코드는 함수를 실행하고, 결과를 tool 메시지로 추가한 다음, 모델이 계속 진행할 수 있도록 API를 다시 호출합니다. 이 핸드셰이크를 올바르게 처리하는 것이 대부분의 에이전트 버그가 발생하는 지점입니다. 배포하기 전에 배선 패턴과 실패 모드를 읽어볼 가치가 있습니다: 에이전트 워크플로우 도구 배선.
Apidog는 여기서도 도움이 됩니다. 전체 다중 턴 교환(초기 요청, 도구 호출 응답, 도구 결과, 후속 조치)을 별도의 저장된 요청으로 재생하여 에이전트 런타임 내에서 추측하는 대신 각 홉을 처음부터 끝까지 확인할 수 있습니다.
멀티모달 입력의 경우, 표준 콘텐츠 부분(content-parts) 형식에 따라 텍스트 프롬프트와 함께 동일한 메시지 배열에 이미지 콘텐츠를 전달합니다. 텍스트 엔드포인트보다 더 빠르게 진화하므로 정확한 필드 이름은 API 참조를 확인하세요.
가격 및 티어
두 가지 별도의 다이얼이 지불하는 금액과 서비스 속도를 제어합니다.
토큰 플랜은 크레딧 예산을 설정합니다. 구독 티어는 Plus($20), Max($50), Ultra($120)로 구성되며, 각 티어는 구독 키로 사용할 수 있는 더 많은 토큰 크레딧을 포함합니다. 종량제는 대신 일반 API 키를 사용하여 잔액에서 청구됩니다.
서비스 티어는 스케줄링 우선순위를 설정합니다. 두 가지가 있습니다: standard (기본값) 및 priority. 표준은 대부분의 워크로드에 적합합니다. 우선순위는 다른 모든 사람 뒤에서 대기할 수 없는 지연 시간에 민감하거나 SLA에 묶인 트래픽을 위한 것입니다.
5단계의 표준 요금과 장문 컨텍스트 요금에 이를 더하면, 실제 비용은 입력 크기, 플랜, 티어에 따라 달라집니다. 현재 토큰당 요금은 공개된 요금이 변경될 수 있으므로 MiniMax 가격 및 모델 페이지와 API 문서를 확인하세요.
자주 묻는 질문
M3를 무료로 사용해 볼 수 있나요? 네. 플랜에 가입하지 않고도 모델을 테스트할 수 있으며, 몇 가지 무료 방법이 있습니다. MiniMax M3 무료 사용 방법에서 이를 정리했습니다.
어떤 SDK가 API와 작동하나요? 세 가지 옵션이 있습니다: 원시 HTTP, Anthropic SDK, OpenAI SDK. MiniMax는 Anthropic SDK를 권장하지만, 세 가지 모두 동일한 https://api.minimax.io/v1/chat/completions 엔드포인트를 사용합니다. OpenAI 및 Anthropic 클라이언트의 경우, base_url만 MiniMax를 가리키도록 변경하면 됩니다.
응답을 어떻게 스트리밍하나요? 요청 본문에 "stream": true를 추가하세요. API는 서버 전송 이벤트를 반환하며, 두 SDK 모두 청크가 도착하는 대로 읽을 수 있도록 이터레이터를 노출합니다. 파싱하기 전에 이벤트 형식을 볼 수 있도록 먼저 Apidog에서 스트림을 테스트하세요.
처리량 제한은 어떻게 되나요? 제한은 계정 티어와 standard 또는 priority 서비스 사용 여부에 따라 달라집니다. 429 오류가 발생하면 잠시 기다렸다가 다시 시도하거나, 지연 시간에 민감한 트래픽을 우선순위 티어로 옮기세요. 현재 수치는 계정 대시보드와 API 문서에 있습니다.
512K 임계값이 청구서에 어떤 영향을 미치나요? 512K 토큰 이하의 입력으로 호출하면 표준 요금이 청구됩니다. 512K 입력 토큰을 초과하면 더 높은 장문 컨텍스트 요금이 적용됩니다. 모델이 실제로 필요로 하는 토큰으로 프롬프트를 줄이세요. 특히 여러 호출에 걸쳐 비용이 가중되는 에이전트 루프에서는 더욱 중요합니다.
API를 호출하는 대신 가중치를 자체 호스팅할 수 있나요? 이 가이드에서 다루는 방법은 호스팅된 API를 사용하는 것이며, 가장 빠르게 시작할 수 있는 방법입니다. 자체 호스팅은 MiniMax가 특정 시점에 M3에 대해 무엇을 게시하는지에 따라 달라지므로, 현재 가중치 및 라이선스 상황은 모델 페이지를 확인하세요.
마무리
이제 MiniMax M3를 호출하는 데 필요한 모든 것을 갖추었습니다: 환경 변수로 저장된 API 키, 작동하는 curl, Python 및 Node 요청, 사고(thinking) 토글, 512K 과금 임계값, 그리고 도구 호출 핸드셰이크. 이를 확실히 하는 가장 빠른 방법은 실제 호출을 수동으로 한 번 실행하는 것입니다. 엔드포인트를 Apidog에 넣고, 베어러 토큰을 환경 변수로 저장하고, 리팩토링 프롬프트를 보내고, 응답을 읽어보세요. 원시 형태를 확인하면 코드로 연결하는 데 몇 분밖에 걸리지 않습니다.