Cómo usar la API de MiniMax H3

MiniMax H3, también buscado como Hailuo 3 o Hailuo 03, es el modelo de última generación de video de MiniMax. Admite tres flujos de trabajo distintos: generar un vídeo a partir de texto, animar una imagen inicial o final y crear un nuevo clip a partir de referencias de imagen, vídeo y audio.

Esta guía muestra cómo acceder a MiniMax H3 a través de EvoLink, elegir el ID de modelo correcto, enviar una solicitud, realizar un seguimiento de la tarea asincrónica y recuperar el video terminado. Los ejemplos utilizan el mismo endpoint de vídeo unificado en los tres modos, por lo que puede agregar H3 a un flujo de trabajo de producción existente sin crear un sistema de tareas separado.

Respuesta rápida

• Punto final: POST https://api.evolink.ai/v1/videos/generations
• Autenticación: Clave API Bearer
• Modelo de texto a vídeo: minimax-h3-text-to-video
• Modelo de imagen a vídeo: minimax-h3-image-to-video
• Modelo de vídeo de referencia: minimax-h3-reference-to-video
• Salida: Vídeo 2K
• Duración: 4 a 15 segundos
• Flujo de tareas: Envíe una solicitud, reciba un ID de tarea y luego sondee el endpoint de la tarea o utilice un callback HTTPS.
• Duración del resultado: Descargue y almacene videos completos dentro de las 24 horas

Índice

1. Qué puede hacer MiniMax H3
2. Características clave y actualizaciones prácticas
3. API MiniMax H3 de un vistazo
4. Cómo acceder al MiniMax H3 API
5. Elija el modo de generación correcto
6. Inicio rápido: envía tu primera solicitud en 60 segundos
7. Comprender el flujo de trabajo asíncrono
8. Ejemplo de texto a vídeo
9. Ejemplos de imagen a vídeo
10. Ejemplo de vídeo de referencia
11. Subir recursos locales
12. Implementación completa de TypeScript
13. Implementación completa de Python
14. Referencia rápida de parámetros y prompts
15. Errores comunes y correcciones
16. Precios y planificación de costos
17. Lista de verificación de producción
18. Casos de uso práctico
19. Preguntas frecuentes

1. Qué puede hacer MiniMax H3

MiniMax H3 está diseñado para la generación de vídeos cortos con diferentes niveles de control creativo. Los tres modos API comparten el mismo ciclo de vida de la tarea pero aceptan entradas diferentes.

La distinción clave es el control. La conversión de texto a vídeo le da al modelo la mayor libertad. La conversión de imagen a vídeo fija la composición en uno o dos fotogramas. El modo de vídeo de referencia le permite describir cómo múltiples recursos de origen deberían influir en el resultado.

2. Funciones clave y actualizaciones prácticas

Los cambios H3 más útiles para los desarrolladores son visibles en el contrato de entrada y salida:

• Tres flujos de trabajo diseñados específicamente. La generación de texto, fotogramas clave y referencias multimodales tienen ID de modelo independientes, pero utilizan un endpoint de EvoLink.
• Salida 2K. Las rutas H3 actuales exponen una única opción de calidad 2k.
• Clips flexibles de 4 a 15 segundos. La duración es un número entero, lo que facilita alinear la duración de la generación con un plan de toma.
• Control del primer y último fotograma. La conversión de imagen a vídeo acepta una imagen inicial, una imagen final o ambas.
• Entradas de referencia más ricas. El modo de vídeo de referencia acepta matrices ordenadas de imágenes, videos y audio, lo que permite una dirección creativa más explícita que una imagen de un solo sujeto.
• Manejo de tareas orientada a la producción. EvoLink proporciona un endpoint de tarea asíncrono consistente y un callback de finalización opcional en los tres modos.

El último punto es una característica de integración de EvoLink, no una capacidad del modelo. Es importante porque una aplicación de producción necesita estados de tareas, callbacks, registros y manejo de resultados predecibles, independientemente del modelo seleccionado.

En qué se diferencia esto de Hailuo 2.3

Ejemplo oficial: referencia de vídeo y voz

3. API MiniMax H3 de un vistazo

Los tres modos utilizan:

POST https://api.evolink.ai/v1/videos/generations

Reglas compartidas:

• duration acepta números enteros del 5 al 15; el valor predeterminado es 5.
• quality debe ser 2k. No envíe 768p.
• Las indicaciones pueden estar escritas en inglés o chino.
• Mantenga las indicaciones dentro de aproximadamente 1000 palabras en inglés o 500 caracteres chinos.
• La tasa de bits, la velocidad de fotogramas y el códec no son configurables.
• La generación es asincrónica.

4. Cómo acceder a la API MiniMax H3

Necesita una cuenta EvoLink, una clave API y crédito suficiente para la tarea solicitada.

1. Cree o inicie sesión en su cuenta EvoLink.
2. Abra el panel de claves API y cree una clave.
3. Almacene la clave en una variable de entorno del lado del servidor.
4. Elija el modo H3 que coincida con sus entradas disponibles.
5. Envíe una solicitud al endpoint de video unificado.

EVOLINK_API_KEY=your_api_key

Nunca exponga esta clave en el JavaScript del navegador, en un repositorio público o en un paquete de aplicaciones móviles. Llame a la API de EvoLink desde su servidor, acción del servidor, ruta API, trabajador u otro tiempo de ejecución confiable.

5. Elija el modo de generación correcto

Utilice esta tabla de enrutamiento antes de construir una carga útil:

6. Inicio rápido: envía tu primera solicitud en 60 segundos

Paso 1: envíe una solicitud de texto a video

curl -X POST https://api.evolink.ai/v1/videos/generations \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-text-to-video",
    "prompt": "A compact electric concept car drives through a rain-soaked city at night. The camera tracks beside the car, then slowly pulls back to reveal neon reflections across the street.",
    "quality": "2k",
    "aspect_ratio": "16:9",
    "duration": 5
  }'

La API devuelve una tarea asincrónica:

{
  "id": "task-unified-example",
  "status": "pending",
  "created": 1785470400
}

Paso 2: verifica la tarea

curl https://api.evolink.ai/v1/tasks/task-unified-example \
  -H "Authorization: Bearer $EVOLINK_API_KEY"

{
  "id": "task-unified-example",
  "status": "completed",
  "results": [
    "https://example-cdn.com/generated-video.mp4"
  ]
}

Descarga el resultado en 24 horas. Cópielo en su propio almacenamiento duradero si su aplicación lo necesita más adelante.

7. Comprenda el flujo de trabajo asíncrono

La generación de vídeo lleva más tiempo que una solicitud HTTP normal. Por lo tanto, la llamada de creación devuelve una tarea en lugar de mantener abierta la conexión hasta que finalice el vídeo.

Submit request
      ↓
Receive task ID
      ↓
pending → processing
      ↓
completed or failed
      ↓
Download completed result

El estado de la tarea puede ser:

• pending: La solicitud está en cola.
• processing: La generación está en curso.
• completed: la matriz results contiene la salida.
• failed: Inspeccione la información del error y decida si la solicitud debe corregirse o volver a intentarse.

¿Polling o callback?

• Utilice HTTPS.
• No debe tener más de 2.048 caracteres.
• Resuelva en un destino público, no en una IP privada.
• Responda en 10 segundos.
• Devuelve una respuesta 2xx después de que se acepte el evento.

Las entregas fallidas se reintentan tres veces con retrasos de aproximadamente 1, 2 y 4 segundos. Su controlador debería estar seguro si el mismo evento se recibe más de una vez.

8. Ejemplo de texto a vídeo

La conversión de texto a vídeo acepta un prompt sin ninguna entrada multimedia.

{
  "model": "minimax-h3-text-to-video",
  "prompt": "A ceramic coffee cup sits on a wooden table beside a window. Morning steam curls upward while the camera makes a slow clockwise orbit. Natural light, realistic texture, quiet editorial mood.",
  "quality": "2k",
  "aspect_ratio": "4:3",
  "duration": 8,
  "callback_url": "https://api.example.com/webhooks/evolink"
}

Las relaciones de aspecto admitidas incluyen:

• 21:9
• 16:9
• 4:3
• 1:1
• 3:4
• 9:16
• Adaptado

9. Ejemplos de imagen a vídeo

Animar una imagen inicial

{
  "model": "minimax-h3-image-to-video",
  "prompt": "The camera slowly moves closer as the fabric responds to a soft breeze. Preserve the product shape, label, and lighting.",
  "image_start": "https://assets.example.com/product-start.webp",
  "quality": "2k",
  "duration": 6
}

Generar hacia un cuadro final

{
  "model": "minimax-h3-image-to-video",
  "prompt": "A wide landscape shot gradually resolves into the supplied final frame, with continuous forward camera movement and stable natural lighting.",
  "image_end": "https://assets.example.com/landscape-end.jpg",
  "quality": "2k",
  "duration": 10
}

Controla tanto el primer como el último fotograma

{
  "model": "minimax-h3-image-to-video",
  "prompt": "The sealed package opens smoothly and the product rises into the final display position. Keep the logo legible and avoid sudden camera cuts.",
  "image_start": "https://assets.example.com/package-closed.png",
  "image_end": "https://assets.example.com/package-open.png",
  "quality": "2k",
  "duration": 8
}

Las imágenes de entrada deben:

• Utilice JPG, JPEG, PNG, WEBP, HEIC o HEIF.
• No superar los 30 MB.
• Tener ancho y alto entre 256 y 5.760 píxeles.
• Tener una relación ancho-alto entre 0,4 y 2,5.
• Estar disponible desde una URL HTTP(S) pública.

10. Ejemplo de vídeo de referencia

El modo de vídeo de referencia acepta matrices ordenadas de imágenes, videos y audio opcional. Es útil cuando un prompt por sí sola no puede describir el tema, el movimiento o el ritmo con suficiente precisión.

{
  "model": "minimax-h3-reference-to-video",
  "prompt": "Use Image 1 for the main character and Image 2 for the wardrobe. Follow the camera movement and walking rhythm from Video 1. Use Audio 1 only as a pacing reference. The character crosses a modern gallery and stops beside a large window.",
  "image_urls": [
    "https://assets.example.com/character.jpg",
    "https://assets.example.com/wardrobe.jpg"
  ],
  "video_urls": [
    "https://assets.example.com/camera-reference.mp4"
  ],
  "audio_urls": [
    "https://assets.example.com/pacing-reference.mp3"
  ],
  "quality": "2k",
  "duration": 10
}

Límites de referencia

• Hasta 9 artículos en image_urls.
• Hasta 3 artículos en video_urls.
• Hasta 3 artículos en audio_urls.
• Como máximo 12 archivos de referencia en total, así que un conjunto completo de 9 + 3 + 3 se rechaza.
• Se requiere al menos una imagen o vídeo.
• El audio no puede ser el único tipo de referencia.
• Los clips de vídeo y audio de referencia deben durar entre 2 y 15 segundos cada uno.
• La duración total del vídeo de referencia no debe exceder los 15 segundos.
• La duración total del audio de referencia no debe exceder los 15 segundos.
• Los videos de referencia deben usar MP4 o MOV con video H.264 o H.265 y pueden contener audio AAC o MP3.
• Cada vídeo de referencia puede tener hasta 50 MB.
• Las dimensiones del vídeo de referencia deben ser de 256 a 5760 píxeles por lado, con una relación ancho-alto de 0,4 a 2,5 y una velocidad de fotogramas de 23,976 a 60 FPS.
• El audio de referencia debe usar WAV o MP3 y puede tener hasta 15 MB por clip.
• El cuerpo completo de la solicitud JSON debe permanecer por debajo de 64 MB.

Las imágenes de referencia siguen el mismo formato, tamaño, dimensión y reglas de URL que la conversión de imagen a vídeo.

Consulte los recursos por orden de matriz

La duración del vídeo de referencia contribuye al uso facturable, así que evite adjuntar clips más largos de lo necesario para la tarea.

11. Cargar recursos locales

Las rutas de generación requieren URL de medios HTTP(S) públicas. Para utilizar un archivo desde un disco local o cargar una aplicación privada, envíelo primero al servicio de archivos EvoLink.

curl -X POST https://files-api.evolink.ai/api/v1/files/upload/stream \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -F "file=@./product-start.png"

12. Implementación completa de TypeScript

Ejecute este ejemplo en un entorno de servidor confiable en Node.js 18 o posterior.

const API_BASE = "https://api.evolink.ai";

type TaskStatus = "pending" | "processing" | "completed" | "failed";

interface VideoTask {
  id: string;
  status: TaskStatus;
  results?: string[];
  error?: {
    code?: string;
    message?: string;
  };
}

interface BaseRequest {
  prompt: string;
  quality?: "2k";
  duration?: number;
  callback_url?: string;
}

type AspectRatio =
  | "adaptive"
  | "21:9"
  | "16:9"
  | "4:3"
  | "1:1"
  | "3:4"
  | "9:16";

// Un tipo por ruta, para que una combinación de campos inválida no compile.
interface TextToVideoRequest extends BaseRequest {
  model: "minimax-h3-text-to-video";
  aspect_ratio?: AspectRatio;
}

interface ImageToVideoRequest extends BaseRequest {
  model: "minimax-h3-image-to-video";
  image_start?: string;
  image_end?: string;
  // Sin aspect_ratio: la ruta rechaza el campo y deriva la relación
  // de aspecto a partir de la imagen de entrada.
}

interface ReferenceToVideoRequest extends BaseRequest {
  model: "minimax-h3-reference-to-video";
  aspect_ratio?: AspectRatio;
  image_urls?: string[];
  video_urls?: string[];
  audio_urls?: string[];
}

type VideoRequest =
  | TextToVideoRequest
  | ImageToVideoRequest
  | ReferenceToVideoRequest;

function getApiKey(): string {
  const apiKey = process.env.EVOLINK_API_KEY;

  if (!apiKey) {
    throw new Error("EVOLINK_API_KEY is not configured");
  }

  return apiKey;
}

async function requestJson<T>(
  path: string,
  init?: RequestInit,
): Promise<T> {
  const response = await fetch(`${API_BASE}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${getApiKey()}`,
      "Content-Type": "application/json",
      ...init?.headers,
    },
  });

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`EvoLink request failed (${response.status}): ${body}`);
  }

  return response.json() as Promise<T>;
}

async function submitVideo(payload: VideoRequest): Promise<VideoTask> {
  return requestJson<VideoTask>("/v1/videos/generations", {
    method: "POST",
    body: JSON.stringify(payload),
  });
}

async function getTask(taskId: string): Promise<VideoTask> {
  return requestJson<VideoTask>(
    `/v1/tasks/${encodeURIComponent(taskId)}`,
  );
}

function wait(milliseconds: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, milliseconds));
}

async function waitForVideo(
  taskId: string,
  timeoutMs = 10 * 60 * 1000,
  pollIntervalMs = 5_000,
): Promise<string> {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const task = await getTask(taskId);

    if (task.status === "completed") {
      const resultUrl = task.results?.[0];

      if (!resultUrl) {
        throw new Error("Task completed without a result URL");
      }

      return resultUrl;
    }

    if (task.status === "failed") {
      throw new Error(task.error?.message ?? "Video generation failed");
    }

    await wait(pollIntervalMs);
  }

  throw new Error(`Timed out while waiting for task ${taskId}`);
}

async function main(): Promise<void> {
  const task = await submitVideo({
    model: "minimax-h3-text-to-video",
    prompt:
      "A slow aerial approach toward a coastal observatory at sunrise, " +
      "natural cloud movement, cinematic wide shot",
    quality: "2k",
    aspect_ratio: "16:9",
    duration: 6,
  });

  const videoUrl = await waitForVideo(task.id);
  console.log(videoUrl);
}

void main();

Para sistemas de gran volumen, reemplace el sondeo del lado de la aplicación con callbacks y un registro de trabajo duradero. Mantenga el ID de la tarea como vínculo principal entre su solicitud, registro de facturación, registros y resultado.

13. Implementación completa de Python

import os
import time
from typing import NotRequired, TypedDict, cast

import requests

API_BASE = "https://api.evolink.ai"
API_KEY = os.environ["EVOLINK_API_KEY"]
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


class VideoError(TypedDict):
    code: NotRequired[str]
    message: NotRequired[str]


class VideoTask(TypedDict):
    id: str
    status: str
    results: NotRequired[list[str]]
    error: NotRequired[VideoError]


class VideoPayload(TypedDict):
    model: str
    prompt: str
    image_start: NotRequired[str]
    quality: NotRequired[str]
    duration: NotRequired[int]


def submit_video(payload: VideoPayload) -> VideoTask:
    response = requests.post(
        f"{API_BASE}/v1/videos/generations",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return cast(VideoTask, response.json())


def get_task(task_id: str) -> VideoTask:
    response = requests.get(
        f"{API_BASE}/v1/tasks/{task_id}",
        headers=HEADERS,
        timeout=30,
    )
    response.raise_for_status()
    return cast(VideoTask, response.json())


def wait_for_video(
    task_id: str,
    timeout_seconds: int = 600,
    poll_interval_seconds: int = 5,
) -> str:
    deadline = time.monotonic() + timeout_seconds

    while time.monotonic() < deadline:
        task = get_task(task_id)
        status = task["status"]

        if status == "completed":
            results = task.get("results", [])
            if not results:
                raise RuntimeError("Task completed without a result URL")
            return str(results[0])

        if status == "failed":
            error = task.get("error", {})
            message = error.get("message", "Video generation failed")
            raise RuntimeError(message)

        time.sleep(poll_interval_seconds)

    raise TimeoutError(f"Timed out while waiting for task {task_id}")


task = submit_video(
    {
        "model": "minimax-h3-image-to-video",
        "prompt": (
            "The camera slowly orbits the product while the background "
            "light shifts from warm to cool. Preserve the product design."
        ),
        "image_start": "https://assets.example.com/product.webp",
        "quality": "2k",
        "duration": 8,
    }
)

print(wait_for_video(task["id"]))

Este ejemplo mantiene la dependencia ligera al mismo tiempo que declara los campos que consume. En un servicio Python más grande, valide la respuesta completa con Pydantic antes de almacenarla.

14. Referencia rápida de parámetros y prompts

Soporte de parámetros

Patrón de prompt: texto a video

[subject] + [action] + [environment] + [camera movement] +
[lighting] + [visual mood]

Ejemplo:

Un ciclista cruza un puente colgante sobre un bosque de niebla al amanecer. La cámara sigue desde atrás y luego se eleva hacia una amplia vista aérea. Luz natural suave y movimiento realista.

Patrón de prompt: imagen a video

[motion to add] + [camera movement] + [elements to preserve] +
[transition or ending state]

Ejemplo:

La cámara traza un lento semicírculo alrededor de la silla mientras la luz del sol se mueve por el suelo. Conserve la forma, el material y el color exactos de la silla.

Patrón de prompt: vídeo de referencia

Use [Image/Video/Audio number] for [specific purpose].
[Describe the new scene, action, camera, and final composition.]

Ejemplo:

Utilice la Imagen 1 para el personaje, la Imagen 2 para el vehículo y el Vídeo 1 para el movimiento de la cámara. El personaje sale del vehículo en un desierto tranquilo al atardecer mientras la cámara hace el mismo arco hacia adelante que el Video 1.

15. Errores comunes y correcciones

Reintente solo los errores que puedan tener éxito sin cambiar la solicitud, como fallas temporales de la red o límites de velocidad. Los parámetros no válidos y los recursos no compatibles deben corregirse antes de realizar otro envío.

16. Precios y planificación de costes

Para fines de planificación:

• Una mayor duración de la producción aumenta el trabajo solicitado.
• El modo de vídeo de referencia también puede facturar la duración del vídeo de referencia de entrada.
• Utilice la duración útil más corta al validar un prompt o flujo de trabajo.
• Realice unas pocas generaciones de prueba y revise los resultados antes de iniciar un lote grande.
• Registre el modo, la duración de salida, la duración del vídeo de referencia, el estado y el coste de cada tarea.
• Separe las generaciones fallidas de los resultados utilizables al calcular el coste por vídeo útil.

La API unificada de EvoLink también permite que un equipo de producción compare H3 con otros modelos de video sin reemplazar su autenticación, seguimiento de tareas e integración de facturación.

17. Lista de verificación de producción

Antes del envío:

• Mantenga la clave API en el servidor.
• Valide todos los parámetros específicos del modo antes del envío.
• Confirme que las URL de los medios sean públicas y permanezcan disponibles durante la generación.
• Establecer tiempos de espera de solicitud.
• Frecuencia de sondeo limitada y tiempo total de sondeo.
• Retroceda después de 429 y errores transitorios del servidor.
• Guarde el ID de la tarea antes de comenzar a sondear.
• No asuma que una tarea H3 se puede cancelar; el contrato de tarea actual informa can_cancel: false.
• Trate los callbacks como eventos repetibles.
• Devuelve una respuesta de callback 2xx solo después de aceptar el evento.
• Conserva los vídeos completados antes de que caduquen sus URL temporales.
• Registre el ID del modelo, la duración, las referencias de entrada, el estado y el resultado.
• Aplique controles presupuestarios y de simultaneidad a nivel de cuenta.
• No dependa de encabezados no documentados ni de configuraciones de salida.

18. Casos de uso prácticos

19. Preguntas frecuentes

¿Cómo accedo a la API MiniMax H3?

¿Qué ID de modelo MiniMax H3 debo usar?

¿MiniMax H3 admite vídeo 2K?

¿La API admite 4K o 60 FPS?

Esos controles no forman parte del contrato API H3 actual. No envíe configuraciones de calidad, velocidad de fotogramas, velocidad de bits o códec no documentadas.

¿Cuál es la duración máxima del vídeo?

El rango de duración actual es de 4 a 15 segundos, utilizando un valor entero.

¿Puedo cargar una imagen local?

¿La API de generación acepta imágenes Base64?

No. Utilice una URL HTTP(S) pública.

¿Cuántas referencias puedo utilizar?

El modo de vídeo de referencia acepta hasta 9 imágenes, 3 videos y 3 archivos de audio, sujetos a los límites por archivo y de duración total.

¿Puedo generar un vídeo solo a partir de una referencia de audio?

No. Una solicitud de referencia debe incluir al menos una imagen o video. Se puede agregar audio como referencia más.

¿Cómo verifico el estado de generación?

¿Durante cuánto tiempo está disponible la URL del vídeo generado?

La URL del resultado está disponible durante 24 horas. Descarga el vídeo o muévelo a tu propio almacenamiento antes de que caduque.

¿Puedo usar MiniMax H3 desde JavaScript o Python?

Sí. La API es HTTPS estándar y se puede llamar desde cualquier entorno del lado del servidor que admita solicitudes JSON y autenticación Bearer.

¿Debo sondear la tarea o utilizar un callback?

El sondeo es conveniente para pruebas y scripts de bajo volumen. Los callbacks suelen ser más eficientes para colas de producción y cargas de trabajo más grandes.

Empieza a crear

• Pruebe MiniMax H3 y revise los detalles del modelo
• Crear una clave API de EvoLink
• Revisar los precios actuales del MiniMax H3
• Abra la referencia de API de texto a video
• Abra la referencia de API de imagen a video
• Abra la referencia API de vídeo de referencia