MiniMax Provider

MiniMax provider는 MiniMax API를 통해 MiniMax-M 시리즈 언어 모델(추론 능력을 가진 모델 포함)과 MiniMax-H 시리즈 비디오 생성에 접근할 수 있게 해 줘요.

API 키는 MiniMax Platform에서 얻을 수 있어요.

출처: 문서

본문

셋업 (Setup)

MiniMax provider는 @ai-sdk/minimax 모듈로 사용할 수 있어요. 다음과 같이 설치하세요:

npm install @ai-sdk/minimax

pnpm add @ai-sdk/minimax

yarn add @ai-sdk/minimax

bun add @ai-sdk/minimax

Provider 인스턴스 (Provider Instance)

@ai-sdk/minimax에서 기본 provider 인스턴스인 minimax을 import할 수 있어요:

import { minimax } from '@ai-sdk/minimax';

커스텀 구성이 필요하면 createMiniMax을 import하고 설정으로 provider 인스턴스를 만들 수 있어요:

import { createMiniMax } from '@ai-sdk/minimax';

const minimax = createMiniMax({
  apiKey: proces..._KEY ?? '',
});

MiniMax provider 인스턴스를 커스터마이즈하려면 다음 선택 설정을 사용할 수 있어요:

baseURL string — API 호출에 다른 URL 접두사를 사용. 이 provider는 MiniMax의 Anthropic 호환 프로토콜을 사용하므로 기본 접두사는 https://api.minimax.io/anthropic/v1 — OpenAI 호환 https://api.minimax.io/v1이 아니에요.
videoBaseURL string — 비디오 생성 API 호출에 다른 URL 접두사를 사용. 비디오 API는 MiniMax V2 네이티브 엔드포인트(Anthropic 호환 엔드포인트가 아님)를 사용해요. 기본 접두사는 https://api.minimax.io.
apiKey string — MiniMax API용 API 키. 기본값은 MINIMAX_API_KEY 환경 변수. 언어 모델은 이를 x-api-key 헤더(Anthropic 호환 프로토콜)로 보내고, 비디오 모델은 Authorization: Bearer ...로 보내요.
headers Record<string,string> — 요청에 포함할 커스텀 헤더.
fetch (input: RequestInfo, init?: RequestInit) => Promise<Response> — 커스텀 fetch 구현.

언어 모델 (Language Models)

provider 인스턴스로 언어 모델을 만들 수 있어요:

import { minimax } from '@ai-sdk/minimax';
import { generateText } from 'ai';

const { text } = await generateText({
  model: minimax('minimax-m3'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

.chat() 또는 .languageModel() 팩토리 메서드도 사용할 수 있어요:

const model = minimax.chat('minimax-m3');
// or
const model = minimax.languageModel('minimax-m3');

MiniMax 언어 모델은 streamText 함수에서도 쓸 수 있어요(AI SDK Core 참고).

추론 (Reasoning)

MiniMax-M 모델은 최종 응답 전에 중간 추론("생각")을 만들 수 있어요. 이 동작은 provider 옵션으로 제어해요. 추론 출력은 표준 AI SDK reasoning 파트로 스트리밍돼요.

import { minimax, type MiniMaxLanguageModelOptions } from '@ai-sdk/minimax';
import { generateText } from 'ai';

const { text, reasoningText } = await generateText({
  model: minimax('minimax-m3'),
  providerOptions: {
    minimax: {
      thinking: { type: 'adaptive' },
    } satisfies MiniMaxLanguageModelOptions,
  },
  prompt: 'How many "r"s are in the word "strawberry"?',
});

console.log(reasoningText);
console.log(text);

챗봇에 추론을 통합하는 자세한 방법은 AI SDK UI: Chatbot을 참고하세요.

Provider 옵션 (Provider Options)

MiniMax 언어 모델에 다음 선택 provider 옵션이 있어요:

thinking object — 모델의 추론("생각") 동작 제어.
- type 'adaptive' | 'disabled'
  - 'adaptive': 모델이 언제 추론할지 스스로 결정 (깊은 추론 활성화)
  - 'disabled': 추론 없이 직접 응답. 더 높은 처리량과 낮은 지연 시간을 위해.
생략하면 모델은 provider 쪽 기본값을 사용해요.

참고: 생각(thinking) 제어는 minimax-m3에서만 지원돼요. M2.x 모델은 항상 생각하므로 'disabled'가 그 모델에는 효과가 없어요.

비디오 모델 (Video Models)

experimental_generateVideo 함수로 MiniMax-H3 및 MiniMax-H3-Max 모델로 비디오를 생성할 수 있어요. MiniMax-H3-Max는 더 빠른 변형으로, 낮은 해상도로 렌더링하고 reference-to-video를 제외한 모든 모드를 제공해요.

import { minimax, type MiniMaxVideoModelOptions } from '@ai-sdk/minimax';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: minimax.video('MiniMax-H3'),
  prompt: 'A white kitten chases a butterfly across a sunlit garden.',
  aspectRatio: '16:9',
  duration: 5,
  providerOptions: {
    minimax: {
      resolution: '768P',
      pollTimeoutMs: 600000, // 10 minutes
    } satisfies MiniMaxVideoModelOptions,
  },
});

두 모델 모두 호출당 비디오 하나를 생성해요. 생성은 비동기예요 — 기본적으로 모델은 작업을 만들고 완료될 때까지 폴링한 뒤, 결과 MP4 URL을 반환해요. 상태 폴링은 첫 요청에 대해 구성된 MiniMax API origin을 신뢰하고, 다른 origin으로의 모든 리다이렉트는 따라가기 전에 검증해요.

duration은 초 단위 정수를 받고 기본값은 5예요. MiniMax-H3는 4~~15초, MiniMax-H3-Max는 5~~15초를 지원해요. 분수 값은 반올림되고 범위를 벗어난 값은 경고와 함께 클램프돼요. MiniMax-H3는 768P와 2K 출력을, MiniMax-H3-Max는 480P와 768P를 지원해요.

API는 프레임 크기가 아니라 이름이 지정된 티어(tier)를 받으므로, 최상위 resolution은 종횡비별 프레임 크기 하나의 고정 테이블과 대조돼요:

Tier	허용된 `resolution` 값
`480P`	`480x480`, `1120x480`, `854x480`, `640x480`, `480x854`, `480x640`
`768P`	`768x768`, `1792x768`, `1366x768`, `1024x768`, `768x1366`, `768x1024`
`2K`	`2048x2048`, `2560x1080`, `2560x1440`, `2048x1536`, `1440x2560`, `1536x2048`

테이블 밖의 값이나 선택한 모델이 지원하지 않는 티어는 경고하고 모델 기본값으로 폴백해요. providerOptions.minimax.resolution은 티어를 정확히 지목하며 최상위 값을 이기는데, 최상위 값은 무시된 것으로 보고돼요.

text-to-video의 경우 aspectRatio를 생략하면 기본값은 16:9예요. MiniMax API는 텍스트 전용 요청에 구체적인 비율을 요구하며 adaptive를 받지 않아요. reference-to-video의 경우 aspectRatio를 생략하면 API 기본값은 adaptive예요. 프레임 이미지가 있는 image-to-video는 종횡비가 입력 이미지를 따라요.

참고: 결과 URL은 시간 제한이 있어요. 생성 후 비디오를 즉시 다운로드해 자체 스토리지에 보존하세요.

비동기 생성 (Asynchronous Generation)

SDK가 시작/상태 흐름을 관리하게 하려면 generateVideo에 poll을 전달하세요:

import { minimax } from '@ai-sdk/minimax';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: minimax.video('MiniMax-H3'),
  prompt: 'A white kitten chases a butterfly across a sunlit garden.',
  poll: { intervalMs: 10000, timeoutMs: 600000 },
});

poll이나 webhook이 없으면 생성은 계속 provider의 pollIntervalMs와 pollTimeoutMs 옵션을 사용해요. poll이 있으면 SDK의 폴링 설정이 대신 적용돼요.

MiniMax는 일반 웹훅 훅을 구현하지 않아요. generateVideo에 webhook을 전달하면 팩토리를 호출하지 않고 SDK 폴링으로 폴백해요. MiniMax의 챌린지 핸드셰이크와 진행 알림은 프로토콜 인식 수신기가 필요하며 일반 SDK 및 Workflow 웹훅 수신기와 호환되지 않아요.

호출자가 일정을 관리하려면 experimental_startVideo로 폴링 없이 작업 하나를 제출하고, experimental_getVideoStatus로 한 번 확인해서 pending, completed, error를 반환받으세요. experimental_startVideo의 완전한 JSON 직렬화 가능 operation을 보존하고, 동일한 구성을 가진 모델의 experimental_getVideoStatus에 그대로 전달하세요. 그 resolvedInputs는 imageCount와 referenceVideoIndices를 담아요: 원래 혼합 inputReferences 배열에서 수락된 URL 비디오 참조의 0부터 시작하는 위치예요. 인라인 비디오는 상한에 포함되지만 인덱스에서는 생략되고, 중복 참조는 별도 인덱스를 유지해요. operation도 status 메타데이터도 입력 URL, 프롬프트, 인라인 데이터, API 자격 증명을 보존하지 않아요. Status 메타데이터는 referenceVideoUrls 대신 이 인덱스들을 사용해요. poll이나 webhook이 없는 일반 generateVideo 호출은 기존 URL 메타데이터를 유지해요. start/status 예시를 참고하세요.

애플리케이션이 관리하는 콜백을 위해 experimental_startVideo에 명시적 webhookUrl을 전달하세요:

import { minimax } from '@ai-sdk/minimax';
import {
  experimental_startVideo as startVideo,
  experimental_getVideoStatus as getVideoStatus,
} from 'ai';

const model = minimax.video('MiniMax-H3');
const { operation } = await startVideo({
  model,
  prompt: 'A white kitten chases a butterfly across a sunlit garden.',
  webhookUrl: 'https://example.com/api/minimax/callback',
});

// Persist operation, then check it from your application's callback handler.
const status = await getVideoStatus(model, { operation });

애플리케이션이 콜백 엔드포인트를 호스팅하고 MiniMax의 콜백 프로토콜을 처리해요. 어댑터는 webhookUrl을 MiniMax의 callback_url로 전달만 해요. 엔드포인트는 검증 challenge를 3초 안에 그대로 에코하고 queued/running 진행 업데이트는 걸러야 해요. task.status가 succeeded, failed, cancelled일 때 종료 알림을 처리한 뒤, 보존된 operation으로 getVideoStatus를 사용해 결과를 가져오세요. 챌린지나 진행 업데이트는 완료를 알리지 않아요. 콜백 계약은 MiniMax V2 API reference를 참고하세요.

생성 모드 (Generation modes)

생성 모드는 전달한 입력에서 추론돼요:

Text-to-video — prompt만.
First-frame image-to-video — image(또는 frameType: 'first_frame'인 frameImages 항목)를 전달해 시작 이미지를 애니메이션.
First-to-last keyframes — frameImages에 first_frame과 last_frame을 모두 전달해 전환 제어.
Reference-to-video (MiniMax-H3만) — inputReferences(이미지 및/또는 비디오, 미디어 타입별 라우팅)를 전달해 주제/스타일 유지 또는 모션 추종. 프레임 이미지와 참조는 상호 배타적이에요. MiniMax-H3-Max는 reference-to-video 입력을 지원하지 않아요.

프레임 이미지가 제공되면 종횡비는 이미지를 따르고 명시적 aspectRatio는 무시돼요.

비디오 provider 옵션 (Video Provider Options)

MiniMax 비디오 모델에 다음 선택 provider 옵션이 있어요:

resolution '480P' | '768P' | '2K' — 출력 해상도. MiniMax-H3는 '768P'와 '2K'(기본값)를 지원. MiniMax-H3-Max는 '480P'와 '768P'(기본값)를 지원.
ratio 'adaptive' | '21:9' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16' — 생성된 비디오의 종횡비. 최상위 aspectRatio를 재정의해요.
referenceAudioUrls string[] — MiniMax-H3 reference-to-video 생성용 참조 오디오 URL(또는 mm_file:// 핸들). 최소 하나의 참조 이미지 또는 비디오와 함께 사용해야 해요. 최대 3개. MiniMax-H3-Max는 참조 오디오를 지원하지 않아요.
aigcWatermark boolean — 출력에 AIGC 워터마크를 포함할지. 기본값 false.
pollIntervalMs number — 작업 상태 폴링 사이 간격(밀리초). 기본값: 10000.
pollTimeoutMs number — 타임아웃 전 폴링할 최대 시간(밀리초). 기본값: 600000.

참고: MiniMax mm_file:// 핸들은 referenceAudioUrls에 대해서만 그대로 전달돼요. image, frameImages, inputReferences에는 사용할 수 없어요: 그 입력들은 AI SDK의 파일 처리를 거치는데, http(s):// 또는 data: URL이 아닌 모든 문자열을 base64 디코딩해요. 그 입력들은 공개 URL, data URI 또는 바이너리 데이터로 전달하세요.

비디오 provider 메타데이터 (Video Provider Metadata)

MiniMax 비디오 결과는 providerMetadata.minimax을 포함해요:

taskId string — MiniMax 생성 작업의 ID.
videoUrl string — MiniMax가 호스팅한 MP4 URL(video와 같은 URL). 시간 제한.
resolvedInputs object — H3이 부과하는 상한과 거부 후 실제로 전송된 입력(경고는 입력이 버려졌다고 알리지만 몇 개가 살아남았는지는 알리지 않아요).
- imageCount number — 전송된 이미지 수(프레임 이미지 또는 참조 이미지).
- referenceVideoUrls string[] — 전송된 참조 비디오의 URL. 인라인 비디오 데이터는 data URI로 전송되므로 생략돼요.
duration number — API가 보고할 때 생성된 비디오 길이(초).
ratio string — API가 보고할 때 생성된 비디오의 종횡비.
resolution string — API가 보고할 때 생성된 비디오의 해상도 티어.
usage object — API가 보고할 때 청구된 초: totalSeconds, inputSeconds, outputSeconds.

모델 기능 (Model Capabilities)

Model	Image Input	Object Generation	Tool Usage	Tool Streaming
`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`	✗	✓	✓	✓

참고: 사용 가능한 모델의 전체 목록은 MiniMax docs를 참고하세요. 필요하면 사용 가능한 provider 모델 ID를 문자열로 전달할 수도 있어요.

MiniMax Provider