MiniMax H3 javascript api: Async Video Setup Guide

MiniMax H3 is a multimodal AI video model released in 2026. It accepts natural-language prompts and can work with images, video, and audio references depending on the selected workflow. The hosted API is designed for asynchronous generation rather than an immediate video response.

For a JavaScript application, the practical sequence is simple: send a request to create a video task, store the returned task_id, query the task until it reaches a terminal status, and retrieve the resulting file with its file_id. The official video generation guide and API reference should be checked whenever endpoint parameters change.

Before writing the request, prepare a server-side Node.js environment and store the key as an environment variable. The following workflow matches the asynchronous pattern documented by MiniMax in 2026.

The following JavaScript example uses the built-in fetch available in modern Node.js runtimes. It creates a task, polls every ten seconds, stops on success or failure, and retrieves the completed file.

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);

The returned download URL should be copied to application storage promptly when your project requires long-term access. Treat the URL as temporary unless the current file API documentation states otherwise.

The JavaScript request controls the task, but prompt quality determines how clearly H3 can interpret the intended scene. Use chronological instructions and avoid conflicting camera movements.

A useful prompt structure is: subject and setting, action and timing, camera movement, lighting and style, dialogue, sound effects, ambience, and final composition.

For reference-based requests, state what each asset controls. For example, identify one image as the character reference and a video as the movement reference. This reduces ambiguity and helps preserve the details that matter most.

Use a staged production workflow: test a short 768P draft, inspect motion and audio, revise only the weak instruction, and reserve higher-resolution output for the selected result. The official pricing documentation explains that costs depend on duration, resolution, workflow, and applicable reference charges.

The hosted API and local H3 weights are different options. The official MiniMax H3 Hugging Face repository provides the open-weight release, while hosted services manage infrastructure, task queues, and file delivery. The reference material identifies H3-Base weights as available, while some hosted Context-IR and 2K regeneration features remain separate services.