MiniMax Messages API (Anthropic 호환)

MiniMax는 Anthropic API의 Messages 형식을 그대로 호환해서, Anthropic을 쓰는 기존 클라이언트로 MiniMax 모델을 호출할 수 있어요. M3 기준으로 이미지·영상 이해, thinking 제어 같은 고급 기능이 Messages 형식 안에서 함께 동작하죠. 이 문서에서는 API 엔드포인트와 요청 형식, 콘텐츠 블록 규칙을 정리해 드릴게요.

출처: MiniMax 공식 문서 - Messages API

API 개요

엔드포인트: POST /anthropic/v1/messages
서버: https://api.minimaxi.com
인증: Authorization: Bearer <API_KEY>(권장) 또는 x-api-key: <API_KEY>. Authorization과 x-api-key가 동시에 있으면 Authorization을 우선해요.
Content-Type: application/json
최신 모델: MiniMax-M3 (Coding/Agentic SOTA, 1M 초장기 컨텍스트, 멀티모달)

주요 요청 파라미터

model: 사용할 모델 ID. MiniMax-M3 및 M2.x 시리즈.
messages: 대화 메시지 배열. M3는 텍스트·이미지·영상·도구 호출·도구 결과·thinking 블록을 지원해요.
max_tokens: 최대 생성 token 수.
thinking: {"type": "adaptive"}로 설정하면 M3의 thinking을 켤 수 있어요. 생략하면 기본 꺼짐.
system: 시스템 프롬프트.
stream: true면 스트리밍 응답.
tools / tool_choice: 도구 정의와 선택 전략.
temperature: 범위 [0, 2] 기본값 1.
top_p: M3 기본 0.95, M2.x 기본 0.9.
service_tier: standard 또는 priority(1.5배 가격, 우선 처리).

콘텐츠 블록

Messages 형식의 content는 여러 타입의 콘텐츠 블록을 담을 수 있어요.

블록 타입	설명
`type="text"`	텍스트 메시지
`type="image"`	M3만. `source`로 URL·base64 입력, JPEG·PNG·GIF·WEBP
`type="video"`	M3만. `source`로 URL·base64, MP4·AVI·MOV·MKV
`type="tool_use"`	도구 호출 블록 (id·name·input 포함)
`type="tool_result"`	도구 호출 결과 (tool_use_id·content 포함)
`type="thinking"`	추론·사고 내용. signature와 함께 원본 그대로 회신

MediaSource의 source는 type(base64·url), base64 입력 시 media_type·data, 공개 URL은 url, 이해 정밀도는 detail(low·default·high, 기본 default), 영상 샘플링 주기는 fps(기본 1, 범위 0.2~5), 가장 긴 변 제한은 max_long_side_pixel로 지정해요.

미디어 형식과 크기 제한

이미지: JPEG(.jpg/.jpeg, image/jpeg), PNG(.png, image/png), GIF(.gif, image/gif), WEBP(.webp, image/webp)
영상: MP4(.mp4, video/mp4), AVI(.avi, video/avi 또는 video/x-msvideo), MOV(.mov, URL일 때 video/quicktime, base64일 때 data:video/mov;base64), MKV(.mkv, video/x-matroska)
URL·base64 입력: 영상 ≤ 50MB, 이미지 ≤ 10MB, 요청 본문 ≤ 64MB
Files API로 업로드한 경우: mm_file://{file_id} 형식 참조, 영상 최대 512MB

토큰 사용량

단일 이미지 token 사용량은 detail에 따라 대략 달라요. 정확한 값은 POST /anthropic/v1/messages/count_tokens 또는 응답 usage로 확인하세요.

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

요청 예시

이미지 이해

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

이미지·영상 예시의 thinking: {"type": "adaptive"}은 M3의 사고 블록을 켜고, 응답에는 thinking 블록(내용 + signature)과 text 블록이 함께 포함돼요. thinking 블록을 다음 턴에 그대로 회신해야 연속성이 유지돼요.

도구 호출

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

tool_use 블록은 id·name·input으로 구성되고, 도구 실행 결과는 tool_use_id와 함께 tool_result 블록으로 되돌려 보내야 해요.

응답 예시 (M3)

M3 응답은 content 배열에 thinking 블록과 text 블록을 함께 담아요. thinking에는 signature가 포함되는데, 다중 턴에서 연속성을 위해 원본 그대로 회신해야 해요.

{
  "id": "066a381bdc3c0ded310e27c9a46d16e7",
  "type": "message",
  "role": "assistant",
  "model": "MiniMax-M3",
  "content": [
    {"type": "thinking", "thinking": "...", "signature": "..."},
    {"type": "text", "text": "이미지에 대한 설명"}
  ],
  "usage": {
    "input_tokens": 1209,
    "output_tokens": 211,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 156
  },
  "stop_reason": "end_turn"
}

MiniMax Messages API (Anthropic 호환)