Cómo usar la API de MiniMax H3 Max para texto e imagen a vídeo

Esta guía sigue el camino más corto hasta una solicitud correcta y después añade validación, consulta de estado, callback, almacenamiento y respaldo para producción. Hasta que se publiquen las páginas de documentación específicas de H3 Max, verifica los campos exactos en el contrato de ruta activo de la página del modelo.

Crea una clave API de EvoLink, consulta la estimación en vivo en la página del modelo MiniMax H3 Max y ten a mano la guía H3 Max vs H3 si tu flujo de trabajo puede necesitar 2K o referencias más amplias.

Requisitos previos

Antes de hacer la primera solicitud, confirma:

Elige el ID de modelo correcto de H3 Max

Paso 1: haz una solicitud de texto a vídeo

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header "Authorization: Bearer $EVOLINK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "minimax-h3-max-text-to-video",
    "prompt": "A premium running shoe rotates on a clean studio pedestal while soft daylight moves across the fabric. Slow camera push-in, realistic material detail, no text or logos added.",
    "duration": 5,
    "quality": "768p",
    "aspect_ratio": "16:9"
  }'

Los parámetros principales de T2V son:

{
  "id": "task-unified-1774857405-abc123",
  "model": "minimax-h3-max-text-to-video",
  "object": "video.generation.task",
  "progress": 0,
  "status": "pending",
  "type": "video"
}

Paso 2: haz una solicitud de imagen a vídeo con primer/último fotograma

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header "Authorization: Bearer $EVOLINK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "minimax-h3-max-image-to-video",
    "prompt": "The camera makes a slow half-orbit as the box opens and the product rises smoothly. Preserve the packaging shape, colors, and lighting; end exactly on the supplied final composition.",
    "image_start": "https://cdn.example.com/h3-max/start.webp",
    "image_end": "https://cdn.example.com/h3-max/end.webp",
    "duration": 8,
    "quality": "768p"
  }'

Cada imagen suministrada debe usar una URL HTTP(S) accesible directamente y cumplir el contrato actual:

• JPG, JPEG, PNG, WEBP, HEIC o HEIF.
• Máximo 30 MB por imagen.
• Ancho y alto entre 256 y 5.760 píxeles.
• Relación ancho/alto de 0,4 a 2,5.
• Como máximo un primer fotograma y un último fotograma.
• Cuerpo JSON completo no superior a 64 MB; no se aceptan Base64 ni mm_file://.

Paso 3: consulta el estado de la tarea

Consulta la tarea con el mismo token Bearer:

curl --request GET \
  --url "https://api.evolink.ai/v1/tasks/task-unified-1774857405-abc123" \
  --header "Authorization: Bearer $EVOLINK_API_KEY"

{
  "id": "task-unified-1774857405-abc123",
  "model": "minimax-h3-max-text-to-video",
  "object": "video.generation.task",
  "progress": 100,
  "status": "completed",
  "results": ["https://files.example.com/generated-video.mp4"],
  "type": "video"
}

Una política de consulta sencilla debería usar un backoff exponencial acotado con jitter en lugar de consultar de forma continua. Por ejemplo: empieza cerca de los dos segundos, crece hasta los 10-15 segundos, detente en un plazo definido por la aplicación y permite que un worker posterior reanude usando el ID de tarea almacenado. El contrato de la API no ofrece cancelación para H3 Max, por lo que un timeout del cliente no debe confundirse con una cancelación en el proveedor.

Paso 4: añade un callback para producción

{
  "model": "minimax-h3-max-text-to-video",
  "prompt": "A cinematic overhead shot of a city block transitioning from morning to night.",
  "duration": 5,
  "quality": "768p",
  "aspect_ratio": "16:9",
  "callback_url": "https://api.example.com/webhooks/evolink/video"
}

El contrato actual de EvoLink exige HTTPS, rechaza destinos con IP privada, espera hasta 10 segundos y reintenta un callback fallido hasta tres veces. Tu gestor debería:

1. Autenticar la solicitud con el mecanismo de verificación configurado en tu aplicación.
2. Usar el ID de tarea como clave de idempotencia.
3. Devolver una respuesta 2xx rápidamente.
4. Trasladar las descargas y el postprocesado pesado a una cola.
5. Conciliar el estado del callback con el endpoint de la tarea antes de la entrega final al cliente cuando sea necesario.

Mantén la consulta de estado disponible como vía de recuperación. Los webhooks pueden retrasarse, ser rechazados por la política de red o procesarse dos veces por la infraestructura de la aplicación.

Valida las solicitudes antes del envío

Gestiona los errores por categoría

Separa los errores HTTP de los fallos de las tareas asíncronas. Una llamada de creación puede tener éxito y la generación fallar más tarde. Registra el ID de tarea, la ruta, la clase de entrada, la duración, la calidad, el estado final, el código de error, el número de reintentos y el resultado del respaldo, sin registrar secretos ni URLs de origen sensibles.

Diseña la transferencia a producción

Guarda la relación entre solicitud y tarea

Crea tu propio ID de trabajo antes del envío. Guarda el ID de tarea de EvoLink, el ID de modelo, los parámetros normalizados, el ID de cliente/espacio de trabajo, las marcas de tiempo y el estado de entrega. Esto hace posibles los reintentos, la auditoría y el soporte incluso si un worker se reinicia.

Descarga los resultados completados con prontitud

Las URLs de resultados de H3 Max están disponibles durante 24 horas. Copia los resultados aceptados a un almacenamiento duradero y registra el checksum o la clave del objeto. No conviertas la URL temporal de origen en el recurso permanente del cliente.

Haz explícitos los reintentos

No envíes una nueva generación porque una solicitud de consulta haya agotado el tiempo de espera. Consulta primero el ID de tarea almacenado. Crea una nueva tarea solo cuando la original haya alcanzado un fallo terminal y tu política de reintentos permita otro intento facturado.

Enruta los trabajos incompatibles antes de la llamada

Mide la salida aceptada

Haz seguimiento de:

• tasa de éxito de las tareas y latencia de finalización;
• aceptación al primer intento y tasa de reintentos;
• coste por clip aceptado;
• adherencia al prompt, a la identidad y a los fotogramas clave;
• tasa de moderación y de solicitudes no válidas;
• frecuencia de respaldo y tasa de recuperación;
• descargas completadas antes de que caduque la URL.

Errores de integración comunes

Lista de comprobación para la puesta en producción

1. La clave API está en el servidor y puede rotarse.
2. T2V e I2V usan esquemas de validación separados.
3. La duración, la calidad, la relación de aspecto y los límites de imagen se aplican localmente.
4. El id de la respuesta de creación se guarda antes de que el worker termine.
5. La consulta de estado usa backoff acotado y puede reanudarse.
6. La gestión de callbacks es idempotente y la consulta de estado sigue disponible.
7. Los MP4 completados se copian en un plazo de 24 horas.
8. Los registros separan errores de solicitud, fallos de tarea y rechazos en revisión.
9. Los precios provienen de la página del modelo o del servicio de precios actual, no de un valor fijo tomado del blog.
10. H3 y un respaldo independiente están probados para trabajos incompatibles o fallidos.

Preguntas frecuentes

¿Qué endpoint usa MiniMax H3 Max en EvoLink?

¿Qué ID de modelo debo usar?

¿La API de H3 Max es síncrona?

¿Puedo generar un vídeo de cuatro segundos con H3 Max?

No. La duración admitida es un entero de 5 a 15 segundos. MiniMax H3, no H3 Max, admite el límite inferior de cuatro segundos en EvoLink.

¿Puedo usar solo un último fotograma?

Sí. El modelo de imagen a vídeo acepta solicitudes con solo primer fotograma, solo último fotograma y con primer y último fotograma.

¿Puedo enviar imágenes en Base64?

¿Imagen a vídeo acepta una relación de aspecto?

No la envíes. La salida sigue la relación del fotograma suministrado. Prepara el fotograma de origen para el formato de entrega previsto.

¿Cuánto tiempo siguen siendo válidas las URLs de resultado?

Veinticuatro horas. Copia los MP4 completados a un almacenamiento duradero como parte del flujo de entrega.

¿Dónde debo consultar los precios actuales?

Usa la sección de precios en vivo y el estimador de la página del producto H3 Max. Evita fijar en el presupuesto de producción una tarifa tomada del blog.

Referencias de API y alcance de verificación

• Página del modelo MiniMax H3 Max y contrato de ruta actual en EvoLink
• Referencia del estado de tareas asíncronas de EvoLink
• Documentación oficial de Video Generation V2 de MiniMax