MiniMax Chat Completions API (OpenAI 호환)

OpenAI의 Chat Completions 형식에 익숙하다면, MiniMax도 같은 형식으로 바로 연동할 수 있어요. POST /v1/chat/completions 하나로 텍스트 생성, 멀티모달 입력, 도구 호출, 스트리밍까지 모두 처리하죠. 이 문서에서는 엔드포인트와 메시지·도구 형식, 파라미터 규칙을 정리해 드릴게요.

출처: MiniMax 공식 문서 - Chat Completions API

API 개요

엔드포인트: POST /v1/chat/completions
서버: https://api.minimax.cn
인증: Authorization: Bearer <API_KEY> (Bearer)
Content-Type: application/json
최신 모델: MiniMax-M3 (Coding/Agentic SOTA, 1M 초장기 컨텍스트, 멀티모달). M3는 thinking 파라미터로 사고를 제어할 수 있어요.

메시지(Message) 형식

요청의 messages 배열은 각 메시지에 role이 필요해요. role 값은 system user assistant tool이며, 같은 역할이 여러 개면 name으로 구분할 수 있어요.

content는 문자열(텍스트) 또는 배열(멀티모달 콘텐츠 블록)이에요. M3는 텍스트·이미지·영상 블록을 지원하고, Files API로 올린 파일은 mm_file://{file_id} 형태로 참조해요.

MessageContentPart

type="text": 텍스트
type="image_url": image_url.url로 이미지 URL 지정
type="video_url": video_url.url로 영상 URL 지정

이미지는 JPEG·PNG·GIF·WEBP, 영상은 MP4·AVI·MOV·MKV를 지원해요. URL·base64 입력 시 영상 ≤ 50MB, 이미지 ≤ 10MB, 요청 본문 ≤ 64MB이고, Files API 참조 영상은 최대 512MB예요.

도구 호출 (ToolCall)

assistant 메시지에는 tool_calls 배열이 올 수 있고, 각 항목은 id·type·function을 가져요.

id: 모델이 생성한 도구 호출 ID
type: 현재 function만 지원
function.name: 호출할 함수 이름
function.arguments: JSON 문자열 형식의 인자

role이 tool인 메시지는 tool_call_id가 필수인데, 이전 assistant 메시지의 tool_calls 중 해당 id를 가져와서 도구 결과를 연결해요.

{
  "model": "MiniMax-M3",
  "messages": [
    {"role": "user", "content": "San Francisco 지금 날씨는 어때?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a given location.",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state/country, e.g. San Francisco, US"
            }
          },
          "required": ["location"]
        }
      }
    }
  ]
}

파라미터 팁

max_completion_tokens: M3 신규 연동 시 권장되는 생성 길이 제한 필드.
thinking: {"type": "adaptive"} 또는 {"type": "disabled"}. M3 기본은 켜짐, M2.x는 끌 수 없음.
temperature: 범위 [0, 2], 기본 1.
top_p: M3 기본 0.95, M2.x 기본 0.9.
stream: true면 스트리밍, stream_options.include_usage=true면 마지막 청크에 token 사용량 포함.
service_tier: standard(기본) 또는 priority(1.5배 가격, 우선 처리).
reasoning_split: true면 thinking을 reasoning_content·reasoning_details로 분리.

멀티모달 요청 예시

{
  "model": "MiniMax-M3",
  "thinking": {"type": "adaptive"},
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "이 이미지의 내용은 무엇인가요?"},
        {
          "type": "image_url",
          "image_url": {
            "url": "https://filecdn.minimax.chat/public/fe9d04da-f60e-444d-a2e0-18ae743add33.jpeg"
          }
        }
      ]
    }
  ],
  "max_completion_tokens": 500
}

영상은 video_url 블록으로 넣고 max_long_side_pixel로 가장 긴 변, fps(0.2~5)로 샘플링 주기를 제어할 수 있어요.

응답 형식

비스트리밍 응답은 choices[i].message에 결과가 들어와요. M3 기본 응답에서 content는 thinking과 response 태그를 함께 포함할 수 있고, reasoning_split=true면 thinking이 reasoning_details로 분리돼요.

{
  "id": "066a2a568140d42ba2020cec72d592c0",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "이미지에 대한 설명"
      }
    }
  ],
  "model": "MiniMax-M3",
  "object": "chat.completion",
  "usage": {
    "total_tokens": 1604,
    "prompt_tokens": 1365,
    "completion_tokens": 239,
    "prompt_tokens_details": {"cached_tokens": 114}
  }
}

usage.prompt_tokens_details.cached_tokens는 프롬프트 캐시가 얼마나 적중했는지를 보여줘요. finish_reason은 stop(자연 종료) 또는 length(max_completion_tokens 상한 도달)로 나와요.

MiniMax Chat Completions API (OpenAI 호환)