MiniMax M3 API 사용법

MiniMax M3는 최대 1,000,000 토큰 컨텍스트 창을 지원하는 추론 및 코딩 모델입니다. 전체 리포지토리, 장기간 로그, 긴 설계 문서를 한 번에 넣고 분석하도록 요청할 수 있습니다. 모델 개요가 필요하다면 먼저 MiniMax M3란 무엇인가를 확인하세요.

오늘 Apidog를 사용해 보세요

이 글에서는 MiniMax M3 API 키를 만들고, curl/Python/Node.js로 첫 요청을 보내고, Apidog에서 요청과 응답을 직접 검증하는 과정을 다룹니다. 따라 하려면 Apidog를 다운로드하세요.

공식 참조는 MiniMax API 문서를 함께 열어두면 좋습니다.

필요한 것

• platform.minimax.io 계정
• MiniMax API 키
• 사용량 결제 수단
  • 종량제 크레딧
  • 구독 토큰 플랜

curl 예제는 별도 설치 없이 실행할 수 있습니다. SDK 예제를 실행하려면 다음이 필요합니다.

• Python 3.8+
• Node.js 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단계: 첫 번째 요청 보내기

MiniMax M3의 기본 설정은 다음과 같습니다.

항목	값
Base URL	https://api.minimax.io/v1
Chat endpoint	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."
      }
    ]
  }'

MiniMax M3는 다음 방식으로 호출할 수 있습니다.

• 원시 HTTP
• OpenAI SDK
• Anthropic SDK

MiniMax는 Anthropic SDK를 권장하지만, OpenAI SDK와 원시 HTTP도 같은 엔드포인트에서 동작합니다. 이미 사용하는 스택에 맞춰 선택하면 됩니다.

Python에서 OpenAI SDK로 호출하기

OpenAI SDK를 사용할 경우 일반 OpenAI 설정과 거의 동일하며, base_url만 MiniMax로 바꾸면 됩니다.

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.minimax.io/v1",
    api_key=os.environ["MINIMAX_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.js에서 OpenAI SDK로 호출하기

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 호환 인터페이스를 제공하므로, 보통 base_url만 교체하면 됩니다.

추가 클라이언트 옵션은 OpenAI Python SDK 문서와 Anthropic SDK 문서를 참고하세요.

3단계: Apidog에서 요청 테스트하기

애플리케이션 코드에 연결하기 전에 요청을 수동으로 보내고 원시 응답을 확인하세요. 이 단계에서 Apidog를 사용하면 헤더, 본문, 응답 구조를 빠르게 검증할 수 있습니다.

Apidog에서 다음 순서로 설정합니다.

1. 새 HTTP 요청을 생성합니다.
2. 메서드를 POST로 설정합니다.
3. URL을 입력합니다.

https://api.minimax.io/v1/chat/completions

1. 환경 변수에 MINIMAX_API_KEY를 추가하고 값을 API 키로 설정합니다.
2. 요청 헤더를 추가합니다.

Authorization: Bearer {{MINIMAX_API_KEY}}
Content-Type: application/json

1. Body를 raw JSON으로 설정합니다.
2. 다음 페이로드를 입력합니다.

{
  "model": "MiniMax-M3",
  "messages": [
    {
      "role": "user",
      "content": "Refactor this function to be async."
    }
  ]
}

1. Send를 누르고 응답 패널을 확인합니다.

[스크린샷: Apidog의 MiniMax-M3 요청 및 응답]

API 키를 환경 변수로 저장하면 팀원과 요청을 공유해도 비밀 값이 노출되지 않습니다. 또한 종량제 키와 구독 키를 바꿔 테스트할 때도 변수 값만 교체하면 됩니다.

스트리밍을 사용할 경우 Apidog에서 서버 전송 이벤트를 먼저 확인하세요. 파싱 코드를 작성하기 전에 실제 이벤트 형식을 볼 수 있어 디버깅 시간이 줄어듭니다.

4단계: 사고 기능 켜고 끄기

MiniMax M3는 추론 모델입니다. 기본적으로 최종 답변만 반환하지만, 필요하면 중간 추론 내용을 별도로 받을 수 있습니다.

OpenAI SDK에서는 extra_body에 reasoning_split을 전달합니다.

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.minimax.io/v1",
    api_key=os.environ["MINIMAX_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"])  # thinking
print(response.choices[0].message.content)  # final answer

reasoning_split을 켜면 다음처럼 응답을 나눠 사용할 수 있습니다.

데이터	위치
사고 내용	response.choices[0].message.reasoning_details[0]["text"]
최종 답변	response.choices[0].message.content

구현 시에는 두 값을 분리하세요.

• 사용자 UI: 최종 답변만 표시
• 로그/검증 파이프라인: 추론 내용 저장 또는 검토

다음과 같은 작업에는 사고 기능을 켜는 것이 유용합니다.

• 다단계 리팩토링
• 복잡한 버그 추적
• 모델 판단 과정을 감사해야 하는 작업

반대로 단순하고 지연 시간에 민감한 호출에서는 끄는 것이 좋습니다. 추가 추론 토큰은 시간과 비용을 증가시킬 수 있습니다.

5단계: 1M 토큰 컨텍스트 활용하기

MiniMax M3를 선택하는 핵심 이유는 큰 컨텍스트 창입니다. 예를 들어 전체 로그 파일을 넣고 특정 장애 원인을 찾도록 요청할 수 있습니다.

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.minimax.io/v1",
    api_key=os.environ["MINIMAX_API_KEY"],
)

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": (
                "Find the root cause of the 502 spike at 14:20 UTC.\n\n"
                f"{log_text}"
            ),
        }
    ],
)

print(response.choices[0].message.content)

다만 컨텍스트가 크다고 항상 전부 넣는 것은 좋지 않습니다.

MiniMax 과금 기준에서 중요한 임계값은 512K 입력 토큰입니다.

입력 크기	과금 방식
512K 입력 토큰 이하	표준 요금
512K 입력 토큰 초과	더 높은 장문 컨텍스트 요금

즉, 400K 토큰 프롬프트에서 600K 토큰 프롬프트로 늘어나는 것은 단순 선형 증가가 아닙니다. 가격 임계값을 넘게 됩니다.

실무에서는 다음 원칙을 적용하세요.

• 모델이 답변에 필요한 부분만 넣습니다.
• 로그나 문서를 먼저 필터링합니다.
• 에이전트 루프에서는 호출당 컨텍스트를 줄입니다.
• 반복 호출되는 프롬프트의 중복 내용을 제거합니다.

비용 최적화는 에이전트 토큰 비용 절감 방법에서 더 자세히 다룹니다.

6단계: 도구 호출 구현하기

MiniMax M3는 도구 호출을 지원합니다. 에이전트가 테스트 실행, 파일 검색, 데이터 조회 같은 작업을 수행하도록 만들 수 있습니다.

기본 흐름은 다음과 같습니다.

1. 모델이 사용할 수 있는 도구를 선언합니다.
2. 모델에 사용자 요청과 도구 목록을 전달합니다.
3. 응답에 tool_calls가 있으면 애플리케이션 코드에서 해당 함수를 실행합니다.
4. 실행 결과를 tool 메시지로 추가합니다.
5. 모델을 다시 호출해 최종 답변을 생성합니다.

예시는 다음과 같습니다.

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 배열이 포함되면 애플리케이션에서 실제 함수를 실행해야 합니다. 모델은 함수를 직접 실행하지 않습니다.

구현 예시는 다음 흐름으로 구성할 수 있습니다.

message = response.choices[0].message

if message.tool_calls:
    for tool_call in message.tool_calls:
        if tool_call.function.name == "run_tests":
            # 실제 테스트 실행 로직을 여기에 연결
            result = run_tests(module="auth/session.py")

            messages = [
                {
                    "role": "user",
                    "content": "Fix the failing test in auth/session.py and confirm it passes.",
                },
                message,
                {
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": result,
                },
            ]

            follow_up = client.chat.completions.create(
                model="MiniMax-M3",
                messages=messages,
                tools=tools,
            )

            print(follow_up.choices[0].message.content)

대부분의 에이전트 버그는 이 핸드셰이크에서 발생합니다.

• tool_call_id 누락
• 도구 실행 결과 형식 불일치
• 모델 메시지 순서 오류
• 실패한 도구 호출 재시도 처리 누락

배포 전에 에이전트 워크플로우 도구 배선을 확인하는 것이 좋습니다.

Apidog에서도 이 흐름을 단계별 요청으로 나눠 재생할 수 있습니다.

• 초기 사용자 요청
• 모델의 도구 호출 응답
• 도구 실행 결과 전달
• 후속 모델 호출

이렇게 하면 에이전트 런타임 내부에서 추측하지 않고 각 홉의 요청/응답을 직접 확인할 수 있습니다.

7단계: 멀티모달 입력 사용하기

MiniMax M3는 텍스트뿐 아니라 이미지 입력도 처리할 수 있습니다.

멀티모달 요청은 표준 콘텐츠 파트 형식에 따라 같은 messages 배열 안에 텍스트와 이미지 콘텐츠를 함께 넣는 방식입니다.

다만 멀티모달 필드는 텍스트 엔드포인트보다 빠르게 바뀔 수 있으므로, 실제 구현 전에는 API 참조에서 최신 필드명을 확인하세요.

가격 및 티어 이해하기

MiniMax M3 비용과 처리 속도에는 두 가지 축이 있습니다.

1. 토큰 플랜

토큰 플랜은 사용할 수 있는 크레딧 예산을 정합니다.

방식	설명
구독 플랜	Plus, Max, Ultra 플랜의 토큰 크레딧을 사용합니다.
종량제	일반 API 키를 사용하고 잔액에서 사용량이 차감됩니다.

구독 티어는 다음과 같습니다.

• Plus: $20
• Max: $50
• Ultra: $120

2. 서비스 티어

서비스 티어는 스케줄링 우선순위에 영향을 줍니다.

티어	용도
standard	기본값. 대부분의 워크로드에 적합합니다.
priority	지연 시간에 민감하거나 SLA가 있는 트래픽에 적합합니다.

실제 비용은 다음 요소에 따라 달라집니다.

• 입력 토큰 수
• 출력 토큰 수
• 512K 입력 토큰 초과 여부
• 종량제 또는 구독 플랜
• standard 또는 priority 서비스 티어

현재 토큰당 요금은 변경될 수 있으므로 MiniMax 가격 및 모델 페이지와 API 문서를 확인하세요.

자주 묻는 질문

M3를 무료로 사용해 볼 수 있나요?

네. 플랜에 가입하지 않고도 테스트할 수 있는 방법이 있습니다. 자세한 내용은 MiniMax M3 무료 사용 방법을 참고하세요.

어떤 SDK가 MiniMax API와 작동하나요?

다음 세 가지 방식이 가능합니다.

• 원시 HTTP
• Anthropic SDK
• OpenAI SDK

MiniMax는 Anthropic SDK를 권장하지만, 세 방식 모두 같은 엔드포인트를 사용합니다.

https://api.minimax.io/v1/chat/completions

OpenAI 또는 Anthropic 클라이언트를 사용할 경우 base_url만 MiniMax로 변경하면 됩니다.

응답을 스트리밍하려면 어떻게 하나요?

요청 본문에 stream을 추가합니다.

{
  "model": "MiniMax-M3",
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "Explain this error log."
    }
  ]
}

API는 서버 전송 이벤트를 반환합니다. SDK에서는 청크가 도착하는 대로 읽을 수 있는 이터레이터를 제공합니다.

파서를 작성하기 전에 Apidog에서 스트림 이벤트 형식을 먼저 확인하는 것이 좋습니다.

처리량 제한은 어떻게 되나요?

제한은 계정 티어와 서비스 티어에 따라 달라집니다.

• standard
• priority

429 오류가 발생하면 잠시 대기 후 재시도하거나, 지연 시간에 민감한 트래픽을 priority 티어로 옮기세요. 최신 제한 수치는 계정 대시보드와 API 문서에서 확인해야 합니다.

512K 임계값은 청구서에 어떤 영향을 주나요?

512K 입력 토큰 이하의 호출에는 표준 요금이 적용됩니다. 512K 입력 토큰을 초과하면 더 높은 장문 컨텍스트 요금이 적용됩니다.

특히 여러 번 반복 호출되는 에이전트 루프에서는 프롬프트를 줄이는 것이 비용 절감에 중요합니다.

API 대신 가중치를 자체 호스팅할 수 있나요?

이 글은 호스팅 API 사용 방법을 다룹니다. 자체 호스팅 가능 여부는 MiniMax가 특정 시점에 M3에 대해 공개한 가중치와 라이선스에 따라 달라집니다. 최신 상태는 모델 페이지를 확인하세요.

마무리

MiniMax M3를 호출하는 기본 흐름은 다음과 같습니다.

1. API 키를 생성합니다.
2. 키를 환경 변수로 저장합니다.
3. https://api.minimax.io/v1/chat/completions로 요청을 보냅니다.
4. MiniMax-M3 모델 ID를 사용합니다.
5. 필요하면 reasoning_split으로 사고 내용을 분리합니다.
6. 큰 컨텍스트를 사용할 때는 512K 입력 토큰 임계값을 확인합니다.
7. 도구 호출은 tool_calls와 tool 메시지 핸드셰이크를 정확히 처리합니다.

가장 빠른 검증 방법은 실제 호출을 한 번 수동으로 실행하는 것입니다. 엔드포인트를 Apidog에 넣고, 베어러 토큰을 환경 변수로 저장한 뒤, 리팩토링 프롬프트를 보내 응답 구조를 확인하세요. 원시 요청과 응답을 이해하면 애플리케이션 코드에 연결하는 작업은 훨씬 단순해집니다.