OpenAI SDK로 MiniMax 모델 호출하기

OpenAI API 형식에 이미 적응한 분이라면 MiniMax도 같은 방식으로 바로 쓸 수 있어요. SDK 설치와 환경 변수 정도만 바꾸면 기존 OpenAI 코드를 거의 그대로 MiniMax 모델에 연결할 수 있죠. 이 문서에서는 설치부터 호출, 멀티모달 입력, 그리고 M3 전용 파라미터까지 정리해 드릴게요.

출처: MiniMax 공식 문서 - OpenAI SDK

빠른 시작

1. OpenAI SDK 설치

Python은 pip install openai, Node.js는 npm install openai로 설치하면 돼요.

2. 환경 변수 설정

export OPENAI_BASE_URL=https://api.minimax.cn/v1
export OPENAI_API_KEY=${YOUR_API_KEY}

3. API 호출

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="MiniMax-M3",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hi, how are you?"},
    ],
    # reasoning_split=True 로 설정하면 사고 내용이 reasoning_details 필드로 분리돼요
    extra_body={"reasoning_split": True},
)

print(f"Thinking:\n{response.choices[0].message.reasoning_details[0]['text']}\n")
print(f"Text:\n{response.choices[0].message.content}\n")

4. 주의할 점

다중 턴 Function Call 대화에서는 모델이 반환한 전체 response_message 객체(파라미터 tool_calls 포함)를 그대로 대화 이력에 추가해야 해요. 원생 OpenAI API의 M3·M2.x 모델은 content 필드에 thinking 태그 내용이 포함되는데 이걸 완전히 보존해야 하고, reasoning_split=True를 쓴 Interleaved Thinking 형식에서는 reasoning_details 필드를 통해 사고 내용이 별도로 제공되니 이것도 그대로 보존해야 해요.

지원 모델

OpenAI SDK에서는 MiniMax-M3 MiniMax-M2.7 MiniMax-M2.7-highspeed MiniMax-M2.5 MiniMax-M2.5-highspeed MiniMax-M2.1 MiniMax-M2.1-highspeed MiniMax-M2 모델을 지원해요. 컨텍스트 윈도우는 M3가 1,000,000, 나머지가 204,800입니다. 자세한 설명은 표준 MiniMax API 문서를 참고하면 돼요.

멀티모달 입력

OpenAI 호환 Chat Completions는 M3에서 텍스트·이미지·영상 입력을 지원해요. 이미지는 image_url 콘텐츠 블록, 영상은 video_url 콘텐츠 블록으로 넣어요. detail 필드는 low default high를 쓸 수 있고 기본은 default예요. max_long_side_pixel로 가장 긴 변을 제어할 수도 있어요. 이미지는 JPEG·PNG·GIF·WEBP, 영상은 MP4·AVI·MOV·MKV를 지원하고 fps 기본값은 1(0.2~5 가능)이에요. URL·base64 영상 최대 50MB, 이미지 최대 10MB, 요청 본문 최대 64MB, 더 큰 영상은 Files API로 올려 mm_file://{file_id}로 참조하고 이때 영상 최대 512MB예요.

response = client.chat.completions.create(
    model="MiniMax-M3",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Summarize what is happening here."},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.png",
                        "detail": "default",
                    },
                },
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "mm_file://file_id",
                        "detail": "default",
                    },
                },
            ],
        }
    ],
)

단일 이미지 token 사용량은 detail에 따라 달라져요. 정확한 값은 응답의 usage로 확인하세요.

`detail`	단일 이미지 대략 token 사용량
`low`	보통 수백 token, 최대 약 600
`default`	보통 1k-3k token, 최대 약 5k
`high`	보통 수천 token, 최대 15k+

MiniMax-M3 요청 파라미터

M3는 OpenAI 호환 인터페이스에서 아래 추가 Chat Completions 파라미터를 지원해요.

파라미터	설명
`thinking`	M3 thinking 제어. `type`은 `disabled` 또는 `adaptive`, 생략하면 기본 켜짐. M2.x는 끌 수 없음
`stream_options.include_usage`	스트리밍 시 `true`로 하면 스트림에 token 사용량 반환
`max_tokens`	구형 생성 길이 제한 파라미터
`max_completion_tokens`	생성 길이 제한. 신규 연동은 이 필드 권장
`temperature`	샘플링 온도. 범위 [0, 2], 기본값 1
`top_p`	핵 샘플링. 범위 [0, 1], M3 기본 0.95, M2.x 기본 0.9
`tools`	함수 도구 정의
`reasoning_split`	출력 형식 스위치. 켜면 thinking을 `reasoning_content`와 `reasoning_details`로 분리
`service_tier`	`standard`·`priority`, 기본 `standard`. `priority`는 1.5배 가격, 우선 처리

Thinking 제어

M3의 thinking 파라미터는 thinking 출력 여부를 제어해요.

생략하면 기본 켜짐, 응답에 thinking 내용이 포함돼요.
thinking: {"type": "adaptive"}으로 명시적으로 켤 수 있어요. M3에서 adaptive는 thinking 켬과 같아요.
thinking: {"type": "disabled"}로 thinking을 건너뛰고 바로 답할 수 있어요.
M2.x 모델은 thinking을 끌 수 없어서 disabled를 보내도 계속 켜져 있어요.

reasoning_split은 thinking을 켜거나 끄지 않고, thinking 반환 방식만 제어해요. true면 reasoning_content와 reasoning_details로, false면 원생 Chat Completions 응답이 thinking을 content 필드의 thinking...response 태그에 유지해요.

response = client.chat.completions.create(
    model="MiniMax-M3",
    messages=[{"role": "user", "content": "Hi, how are you?"}],
    extra_body={
        "thinking": {"type": "adaptive"},
    },
)

예시 코드: 스트리밍 응답

from openai import OpenAI

client = OpenAI()

stream = client.chat.completions.create(
    model="MiniMax-M3",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hi, how are you?"},
    ],
    extra_body={"reasoning_split": True},
    stream=True,
)

reasoning_buffer = ""
text_buffer = ""

for chunk in stream:
    if (
        hasattr(chunk.choices[0].delta, "reasoning_details")
        and chunk.choices[0].delta.reasoning_details
    ):
        for detail in chunk.choices[0].delta.reasoning_details:
            if "text" in detail:
                reasoning_text = detail["text"]
                new_reasoning = reasoning_text[len(reasoning_buffer) :]
                if new_reasoning:
                    print(new_reasoning, end="", flush=True)
                    reasoning_buffer = reasoning_text

    if chunk.choices[0].delta.content:
        content_text = chunk.choices[0].delta.content
        new_text = content_text[len(text_buffer) :] if text_buffer else content_text
        if new_text:
            print(new_text, end="", flush=True)
            text_buffer = content_text

print(f"\n{text_buffer}\n")

주의사항

temperature 범위는 [0, 2], 1.0을 권장해요. 범위를 벗어나면 오류가 나요.
presence_penalty frequency_penalty logit_bias 같은 일부 OpenAI 파라미터는 무시돼요.
M3는 OpenAI 호환 콘텐츠 블록으로 이미지·영상 입력이 가능하지만, 현재 오디오 입력은 지원하지 않아요.
n 파라미터는 값 1만 지원해요.
구형 function_call은 폐기됐고 tools 파라미터를 써야 해요.

OpenAI SDK로 MiniMax 모델 호출하기