MiniMax H3 JavaScript API: 비동기 비디오 설정 가이드

MiniMax H3는 2026년에 출시된 멀티모달 AI 비디오 모델입니다. 자연어 프롬프트를 받아들이며, 선택한 워크플로에 따라 이미지, 비디오, 오디오 참조와 함께 사용할 수 있습니다. 호스팅 API는 즉시 비디오를 반환하는 방식이 아니라 비동기 생성용으로 설계되었습니다.

JavaScript 애플리케이션에서는 실제 순서가 단순합니다. 비디오 작업 생성 요청을 보내고, 반환된 task_id를 저장한 뒤, 작업이 종료 상태에 도달할 때까지 조회하고, 최종적으로 file_id로 결과 파일을 가져오면 됩니다. 엔드포인트 파라미터가 변경될 수 있으므로 공식 비디오 생성 가이드와 API 레퍼런스를 항상 확인하세요.

요청을 작성하기 전에 서버 측 Node.js 환경을 준비하고 키를 환경 변수로 저장하세요. 아래 워크플로는 MiniMax가 2026년에 문서화한 비동기 패턴과 일치합니다.

다음 JavaScript 예제는 최신 Node.js 런타임에서 사용할 수 있는 기본 제공 fetch를 사용합니다. 작업을 생성하고, 10초마다 폴링하며, 성공 또는 실패 시 중지하고, 완료된 파일을 가져옵니다.

const apiKey = process.env.MINIMAX_API_KEY;
const baseUrl = "https://api.minimax.io/v1";

if (!apiKey) throw new Error("MINIMAX_API_KEY is not configured");

const headers = {
  Authorization: `Bearer ${apiKey}`,
  "Content-Type": "application/json"
};

async function createVideo() {
  const response = await fetch(`${baseUrl}/video_generation`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      model: "MiniMax-H3",
      prompt:
        "A cinematic product reveal on black glass, soft violet lighting, slow camera movement, subtle mechanical sound.",
      duration: 6,
      resolution: "768P"
    })
  });

  if (!response.ok) {
    throw new Error(`Create failed with HTTP ${response.status}`);
  }

  const data = await response.json();
  return data.task_id;
}

async function queryVideo(taskId) {
  const response = await fetch(
    `${baseUrl}/query/video_generation?task_id=${encodeURIComponent(taskId)}`,
    { headers }
  );

  if (!response.ok) {
    throw new Error(`Query failed with HTTP ${response.status}`);
  }

  return response.json();
}

async function retrieveVideo(fileId) {
  const response = await fetch(
    `${baseUrl}/files/retrieve?file_id=${encodeURIComponent(fileId)}`,
    { headers }
  );

  if (!response.ok) {
    throw new Error(`File retrieval failed with HTTP ${response.status}`);
  }

  const data = await response.json();
  return data.file?.download_url || data.download_url;
}

async function main() {
  const taskId = await createVideo();

  while (true) {
    const task = await queryVideo(taskId);

    if (task.status === "Success") {
      const downloadUrl = await retrieveVideo(task.file_id);
      console.log({ taskId, fileId: task.file_id, downloadUrl });
      break;
    }

    if (task.status === "Fail") {
      throw new Error(task.error_message || "Video generation failed");
    }

    await new Promise(resolve => setTimeout(resolve, 10000));
  }
}

main().catch(console.error);

프로젝트에서 장기 접근이 필요하다면 반환된 다운로드 URL은 즉시 애플리케이션 저장소로 복사하세요. 현재 파일 API 문서에 별도 명시가 없는 한, URL은 임시로 취급하세요.

JavaScript 요청은 작업을 제어하지만, 프롬프트 품질이 H3가 의도한 장면을 얼마나 명확하게 해석하는지를 결정합니다. 시간 순서에 맞는 지시를 사용하고 서로 충돌하는 카메라 움직임은 피하세요.

유용한 프롬프트 구조는 다음과 같습니다: 대상과 배경, 동작과 타이밍, 카메라 움직임, 조명과 스타일, 대화, 효과음, 분위기, 최종 구도.

참조 기반 요청에서는 각 자산이 무엇을 제어하는지 명시하세요. 예를 들어 한 이미지는 캐릭터 참조, 비디오는 모션 참조로 지정하세요. 이렇게 하면 모호성이 줄어들고 가장 중요한 디테일을 보존하는 데 도움이 됩니다.

단계적 제작 워크플로를 사용하세요: 짧은 768P 초안을 테스트하고, 모션과 오디오를 검토한 뒤, 약한 지시만 수정하고, 선택된 결과에 대해서만 더 높은 해상도를 사용하세요. 공식 가격 문서에서는 비용이 길이, 해상도, 워크플로, 적용 가능한 참조 요금에 따라 달라진다고 설명합니다.

호스티드 API와 로컬 H3 가중치는 서로 다른 선택지입니다. 공식 MiniMax H3 Hugging Face 저장소는 오픈 웨이트 배포를 제공하는 반면, 호스티드 서비스는 인프라, 작업 큐, 파일 전달을 관리합니다. 참고 자료에는 H3-Base 가중치가 사용 가능하다고 나와 있지만, 일부 호스티드 Context-IR 및 2K 재생성 기능은 별도 서비스로 남아 있습니다.