API de JavaScript de MiniMax H3: Guía de configuración para video asíncrono

MiniMax H3 es un modelo multimodal de video con IA lanzado en 2026. Acepta indicaciones en lenguaje natural y puede trabajar con referencias de imágenes, video y audio según el flujo de trabajo seleccionado. La API alojada está diseñada para la generación asíncrona, no para una respuesta inmediata de video.

Para una aplicación JavaScript, la secuencia práctica es simple: enviar una solicitud para crear una tarea de video, guardar el task_id devuelto, consultar la tarea hasta que alcance un estado terminal y recuperar el archivo resultante con su file_id. La guía oficial de generación de video y la referencia de la API deben revisarse siempre que cambien los parámetros del endpoint.

Antes de escribir la solicitud, prepara un entorno Node.js del lado del servidor y almacena la clave como una variable de entorno. El siguiente flujo de trabajo coincide con el patrón asíncrono documentado por MiniMax en 2026.

El siguiente ejemplo de JavaScript usa fetch integrado disponible en los runtimes modernos de Node.js. Crea una tarea, consulta cada diez segundos, se detiene en caso de éxito o fallo y recupera el archivo completado.

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

La URL de descarga devuelta debe copiarse rápidamente al almacenamiento de la aplicación cuando tu proyecto requiera acceso a largo plazo. Trata la URL como temporal, a menos que la documentación actual de la API de archivos indique lo contrario.

La solicitud de JavaScript controla la tarea, pero la calidad de la indicación determina con qué claridad H3 puede interpretar la escena prevista. Usa instrucciones cronológicas y evita movimientos de cámara contradictorios.

Una estructura útil para la indicación es: sujeto y entorno, acción y momento, movimiento de cámara, iluminación y estilo, diálogo, efectos de sonido, ambiente y composición final.

Para solicitudes basadas en referencias, indica qué controla cada activo. Por ejemplo, identifica una imagen como referencia del personaje y un video como referencia del movimiento. Esto reduce la ambigüedad y ayuda a preservar los detalles que más importan.

Usa un flujo de trabajo de producción por etapas: prueba un borrador corto en 768P, inspecciona el movimiento y el audio, revisa solo la instrucción débil y reserva la salida de mayor resolución para el resultado seleccionado. La documentación oficial de precios explica que los costos dependen de la duración, la resolución, el flujo de trabajo y los cargos de referencia aplicables.

La API alojada y los pesos locales de H3 son opciones distintas. El repositorio oficial de MiniMax H3 en Hugging Face ofrece la versión de pesos abiertos, mientras que los servicios alojados gestionan la infraestructura, las colas de tareas y la entrega de archivos. El material de referencia identifica los pesos H3-Base como disponibles, mientras que algunas funciones alojadas de Context-IR y regeneración en 2K siguen siendo servicios separados.