Cómo escribir prompts de video desde imagen con múltiples ángulos usando minimax-h3-max a través de la API de hiapi

minimax-h3-max puede convertir una foto en un video de 5 a 15 segundos, pero su endpoint no tiene ningún parámetro de «ángulo de cámara», «múltiples vistas» o «número de planos»: los campos de entrada admitidos que enumera la referencia de parámetros son prompt, first_frame_image, last_frame_image, duration, resolution y aspect_ratio. Las instrucciones de cámara se escriben dentro de prompt, campo que acepta hasta 7.000 caracteres.

Por lo tanto, un clip de «múltiples ángulos» —que pasa de un plano general de establecimiento a un primer plano y luego a un plano de seguimiento— no es un parámetro que configures, sino un prompt que escribes. Este tutorial cubre la estructura de la solicitud, los patrones de prompt para pedir varios ángulos de cámara dentro de un mismo clip generado, y el flujo de nivel producción que lo rodea.

Generar con este prompt → Elige 10 segundos y 768P. Si haces video desde imagen, añade tu imagen de fotograma y omite aspect_ratio.

Requisitos previos

Obtén una clave de API desde tu consola de hiapi. Cada llamada a continuación se autentica con Authorization: Bearer YOUR_API_KEY contra el endpoint compartido de tareas asíncronas POST https://api.hiapi.ai/v1/tasks.

Ejemplo mínimo: una foto, tres ángulos de cámara

first_frame_image ancla el sujeto y la escena, de modo que el modelo tiene contenido concreto del que cortar y al que volver. El prompt describe cada plano como un corte numerado explícito. Este prompt de la motocicleta es un ejemplo de código y no incluye una muestra renderizada.

Una motocicleta vintage roja aparcada en una calle urbana mojada al atardecer, con letreros de neón reflejándose en el pavimento. Plano 1 - gran angular bajo: la cámara mantiene un plano general estático de la motocicleta completa, con lluvia ligera cayendo. Corte al plano 2 - primer plano: la cámara se acerca hasta quedar muy cerca del faro cromado y la rueda delantera, desplazándose lentamente hacia la derecha. Corte al plano 3 - cenital desde arriba: la cámara mira directamente hacia abajo a la motocicleta desde arriba, girando lentamente. Sin texto ni subtítulos.

Generar con este prompt → Añade tu propia imagen de motocicleta accesible públicamente, elige 10 segundos y 768P, y omite aspect_ratio.

import os
import requests
import time

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

payload = {
    "model": "minimax-h3-max",
    "input": {
        "prompt": (
            "A red vintage motorcycle parked on a wet city street at dusk, neon signs reflecting on the pavement. "
            "Shot 1 - low wide angle: the camera holds a static wide shot of the full motorcycle, rain lightly falling. "
            "Cut to Shot 2 - close-up: the camera pushes in tight on the chrome headlight and front wheel, tracking slowly right. "
            "Cut to Shot 3 - overhead top-down: the camera looks straight down at the motorcycle from above, slowly rotating. "
            "No text or subtitles."
        ),
        "first_frame_image": "https://your-cdn.example.com/motorcycle-source.jpg",
        "duration": 10,
        "resolution": "768P",
    },
}

# Frame images and aspect_ratio are mutually exclusive.
def response_data(response):
    response.raise_for_status()
    body = response.json()
    if not isinstance(body, dict) or body.get("code") != 200:
        raise ValueError("Expected a JSON object with code=200")
    data = body.get("data")
    if not isinstance(data, dict):
        raise ValueError("Expected data to be an object")
    return data

# Submit once. An uncertain POST response is not a reason to submit again.
try:
    resp = requests.post(
        f"{BASE}/tasks", headers=HEADERS, json=payload, timeout=(10, 60)
    )
    created = response_data(resp)
    task_id = created.get("taskId")
    if not isinstance(task_id, str) or not task_id.strip():
        raise ValueError("Missing data.taskId")
except (requests.RequestException, ValueError) as exc:
    raise RuntimeError(
        "Could not confirm task creation. Check task records before resubmitting."
    ) from exc

print("taskId:", task_id, flush=True)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    try:
        resp = requests.get(
            f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=(10, 60)
        )
        task = response_data(resp)
    except (requests.RequestException, ValueError) as exc:
        raise RuntimeError(
            f"Query failed; retain taskId={task_id} and resume GET for this ID."
        ) from exc

    state = task.get("status")
    if state == "fail":
        raise RuntimeError(f"Task {task_id} failed: {task.get('error')}")
    if state == "success":
        outputs = task.get("output")
        if not isinstance(outputs, list):
            raise RuntimeError(f"Task {task_id}: missing output array")
        video = next(
            (item for item in outputs
             if isinstance(item, dict) and item.get("type") == "video"
             and isinstance(item.get("url"), str) and item["url"]),
            None,
        )
        if video is None:
            raise RuntimeError(f"Task {task_id}: no video URL in output")
        print(video["url"])
        print("expireAt (Unix seconds):", video.get("expireAt"))
        break
    if state not in {"queued", "handling", "archiving"}:
        raise RuntimeError(f"Task {task_id}: unexpected status {state!r}")
    time.sleep(min(3, max(0, deadline - time.monotonic())))
else:
    raise TimeoutError(f"Polling timed out; continue GET with taskId={task_id}")

Cambia first_frame_image por una URL de imagen HTTPS real y accesible públicamente, o elimínala por completo y genera la misma secuencia multiángulo solo con texto: minimax-h3-max gestiona tanto texto a video como imagen a video mediante el mismo campo prompt.

Escribir prompts: el patrón de planos numerados

Tres decisiones hacen que tu secuencia de planos objetivo sea inequívoca:

1. Una frase que establezca la escena y luego planos numerados. Describe el sujeto y la escena una vez, después enumera cada ángulo de cámara como un compás etiquetado propio: Plano 1 - [composición]: [acción]. Corte al plano 2 - [composición]: [acción]. «Corte al plano N» es una petición explícita de cambiar el ángulo de cámara.
2. Usa vocabulario cinematográfico estándar. plano general en ángulo bajo, plano cenital desde arriba, primer plano, lento acercamiento de cámara, plano de seguimiento lateral, cámara en mano: estas palabras indican la composición y el movimiento que deseas. Formulaciones vagas como «otro ángulo molón» producen resultados inconsistentes.
3. Planifica el número de planos según la duración. duration es un número entero de 5 a 15 segundos. Dos o tres planos son realistas; meter cinco ángulos distintos en un clip de 5 segundos deja menos de un segundo por plano y a menudo parece un fallo en lugar de un corte.

first_frame_image y last_frame_image son ambos opcionales e independientes entre sí: puedes establecer uno, ambos o ninguno. Cuando proporciones cualquiera de ellos, omite aspect_ratio: estos campos son mutuamente excluyentes y las imágenes de fotograma determinan la relación de aspecto de la salida. Ten en cuenta también que no se garantiza una estricta coherencia tridimensional o geométrica entre ángulos: es un modelo de video generativo, no una canalización de fotogrametría, así que incluso con un fotograma inicial anclado, espera una ligera deriva en los detalles del sujeto entre cortes.

Prepararlo para producción

• Prefiere callbacks al polling en cuanto superes la escala de script. Añade "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"} al cuerpo de la solicitud y hiapi hará un POST de notificación cuando la tarea llegue a un estado terminal, en lugar de que tú consultes GET /v1/tasks/{taskId} en un bucle.
• Deduplica por taskId. Tanto las respuestas de polling como los callbacks se identifican por el mismo taskId: trata las notificaciones repetidas de estado terminal con el mismo ID como idempotentes, no como varias tareas independientes.
• Descarga la salida de inmediato. Las tareas correctas devuelven data.output[].url apuntando a almacenamiento temporal. Selecciona el elemento de salida cuyo type sea video y comprueba su marca de tiempo Unix expireAt (en segundos). Vuelve a subirlo a tu propio almacenamiento en el mismo manejador que procesa el estado terminal.
• Gestiona las dos formas de fallo. Un cuerpo de solicitud incorrecto (campos no admitidos, duration fuera de rango, URL de imagen mal formada) falla rápidamente al enviarse con 400 INVALID_REQUEST. Los problemas de autenticación devuelven 401 con error.code: "permission_denied". Las tareas que fallan durante la generación informan "status": "fail" en la respuesta de polling/callback: comprueba status antes de confiar en output.

Lecturas relacionadas

• Página del modelo minimax-h3-max: precios en vivo, parámetros y un playground para probar prompts en el navegador antes de integrarlos en tu código.
• Documentación de la API de minimax-h3-max: referencia completa de parámetros y detalles de los callbacks.
• Precios de H3 y H3 Max: tarifas por resolución y presupuesto para clips cortos.
• Precios de hiapi: tarifas actuales por segundo de cada modelo.

Preguntas frecuentes

¿minimax-h3-max tiene un parámetro dedicado de múltiples ángulos o múltiples cámaras? No. Los campos de entrada documentados son prompt, first_frame_image, last_frame_image, duration, resolution y aspect_ratio. Describe varios planos dentro de prompt en lugar de añadir un campo de ángulo de cámara.

¿Puedo establecer aspect_ratio junto con first_frame_image o last_frame_image? No. aspect_ratio es mutuamente excluyente con cualquiera de los campos de imagen de fotograma. La imagen proporcionada determina la relación de aspecto de la salida. Siempre que pases cualquier imagen de fotograma, omite aspect_ratio.

¿Cuánto puede durar un clip multiángulo? duration acepta un número entero de 5 a 15 segundos. Dos o tres ángulos de cámara distintos caben con cierta holgura en esa ventana; superar esa cantidad suele comprimir cada plano a una fracción de segundo.

¿El sujeto se mantendrá perfectamente consistente entre ángulos? No está garantizado. minimax-h3-max es un modelo de video generativo, así que incluso si first_frame_image ancla el fotograma inicial, los detalles (texturas exactas, proporciones sutiles) pueden derivar entre cortes. Trátalo como una fuerte consistencia creativa, no como una reconstrucción multiángulo precisa a nivel de píxel.

¿Puedo generar un clip multiángulo solo con texto, sin imagen de origen? Sí: omite first_frame_image y last_frame_image y describe la escena y los planos en prompt. La generación solo con texto usa el lienzo horizontal predeterminado. Para una composición vertical, proporciona una imagen de fotograma vertical sin establecer aspect_ratio, o recorta/rellena el video guardado en el editor.

¿Cómo se ve un fallo de autenticación? HTTP 401, con un cuerpo de respuesta similar a {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"..."}}. Revisa con cuidado la cabecera Authorization: Bearer y si la clave ha sido revocada desde la consola.

Copia la secuencia de planos de la motocicleta y genera con este prompt → elige 10 segundos y 768P; añade tu imagen de fotograma para guiar la composición inicial.