Blog

Tutorial

Cómo usar pixverse-v6-max de imagen a video a través de la API de HiAPI: curl, Python y una solicitud que funciona

Nov 13, 2026
Imagen de portada de estilo editorial plano: sobre un fondo verde pino profundo, un gran prisma segmentado en bloques de color verde salvia y verde neblina.
En esta página

Qué requiere el endpoint de imagen a video pixverse-v6-max

El endpoint pixverse-v6-max/image-to-video de HiAPI es una tarea de generación de video asíncrona condicionada por una imagen. Esta sola frase determina casi todas las decisiones que tomarás al integrarlo.

El endpoint recibe una imagen de origen (primer fotograma) y un conjunto de parámetros de generación, y devuelve una referencia de tarea, no el video final. La renderización real ocurre en el servidor y puede tardar desde unos segundos hasta varios minutos según los parámetros que elijas. Tu cliente es responsable de enviar la tarea y luego consultar su estado repetidamente hasta que informe un estado terminal.

Compáralo con la edición de imágenes síncrona: en la edición síncrona, haces POST de un cuerpo de solicitud y recibes la imagen transformada en la misma respuesta HTTP. Aquí el flujo es:

  1. Haz POST de tu imagen y parámetros al endpoint de generación.
  2. Recibe un identificador de tarea (normalmente con un estado inicial).
  3. Haz GET del estado de la tarea a intervalos hasta que se complete o falle.
  4. Lee la URL del video generado del cuerpo de respuesta de la tarea completada.

Debido a esta separación, existen dos clases distintas de errores: problemas en la fase de envío (errores de autenticación, cuerpo de solicitud mal formado, imagen rechazada) y problemas en la fase de ejecución (la tarea se acepta pero falla o se estanca). Una buena integración maneja ambos explícitamente; consulta la sección de solución de problemas más adelante para ver la lista de verificación concreta.

Otro punto a tener en cuenta: la imagen de origen es el ancla. El modelo anima a partir de este primer fotograma, por lo que la calidad, la relación de aspecto y el contenido de la imagen influyen en la salida más que cualquier texto de prompt que proporciones. Trata la corrección de la carga como una preocupación principal, no como algo secundario.

Prepara tu clave de API y el endpoint

Antes de enviar tu primera solicitud, solo necesitas dos cosas: una clave de API de HiAPI y la URL base correcta para el endpoint.

Obtén tu clave

Crea una clave de API en la consola de tu cuenta de HiAPI. Trátala como una contraseña: guárdala en una variable de entorno, no en el código fuente ni en el historial del shell.

export HIAPI_API_KEY="your_key_here"

Si usas un archivo .env localmente, agrégalo a .gitignore antes de confirmar cualquier cosa. Cualquier clave que aparezca en registros compartidos, capturas de pantalla o repositorios de código debe rotarse de inmediato.

Conoce tu URL base y ruta

El endpoint se encuentra bajo el host de la API de HiAPI, con la ruta del modelo pixverse-v6-max/image-to-video. En los ejemplos siguientes, la URL base se muestra como https://api.hiapi.ai y la ruta completa se construye concatenándola. Si tu cuenta o región te proporciona un host diferente, sustitúyelo de manera consistente: un desajuste entre host y clave es una de las causas más comunes de 401, que los desarrolladores a menudo confunden erróneamente con una "clave inválida".

Elige tus herramientas

  • curl para una primera verificación rápida: elimina todas las variables excepto la solicitud en sí.
  • Python 3 con requests (o httpx) para la integración real.
python3 -c "import requests; print(requests.__version__)"

Si imprime un número de versión, estás listo. Los ejemplos de este artículo no requieren instalar un SDK; todo es HTTP puro, lo que también significa que puedes portarlo a cualquier lenguaje más adelante. Una vez confirmados la clave y el host, puedes empezar a construir la solicitud.

Construye la solicitud con curl

Comienza con la solicitud mínima que realmente funcione y luego agrega parámetros. El siguiente cuerpo de solicitud muestra la estructura de un envío completo de imagen a video.

curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://your-cdn.example.com/first-frame.jpg",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

Aquí suceden tres cosas:

  • La autenticación se transporta en el encabezado Authorization como un token bearer.
  • El cuerpo es JSON, por lo que la imagen se proporciona como una cadena de URL (consulta la siguiente sección para saber cómo pasar un archivo local en su lugar).
  • Dos parámetros de generación —duration y aspect_ratio— son campos de nivel superior.

Un envío exitoso devuelve un objeto JSON que contiene un identificador de tarea. Captúralo:

JOB_ID=$(curl -s -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"https://your-cdn.example.com/first-frame.jpg","duration":5,"aspect_ratio":"16:9"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
echo "$JOB_ID"

Luego consúltalo:

curl -s "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

En caso de fallo, siempre verifica el campo de estado y el cuerpo de error sin procesar. curl puede imprimir JSON de error incluso cuando el código de salida es 0, así que no dependas únicamente del código de salida en scripts.

Proporciona correctamente la imagen del primer fotograma

La imagen de origen es el punto de fallo más común; casi todos los rechazos se reducen a una de las siguientes cuatro causas.

1. La imagen no es accesible

Cuando pasas una URL, los servidores de HiAPI deben poder hacer GET a ella, desde su red, no desde la tuya. Una URL de localhost, un bucket privado, una URL firmada que expira en sesenta segundos o un endpoint detrás de una VPN fallarán. Usa una URL de almacenamiento de objetos públicamente legible o un enlace CDN, y confirma que se carga en una sesión de navegador nueva sin cookies.

2. Formato de imagen no compatible

Cíñete a formatos web estándar: JPEG, PNG, WebP. Archivos con extensiones poco comunes, HEIC de cámaras de teléfonos o GIF animados son riesgosos. Si tu canal de producción genera algún formato exótico, transcodifícalo primero.

3. El primer fotograma no coincide con la relación de aspecto declarada

Esto es más sutil. Si tu imagen de origen es cuadrada pero solicitas 16:9, el servicio tendrá que recortar, rellenar o rechazar la entrada. El comportamiento puede variar, y ninguno de los tres es lo que la mayoría de los desarrolladores desea. Recorta o agrega barras negras tú mismo antes de subir para que la geometría de la imagen ya coincida con el aspect_ratio que vas a solicitar. Esto hace que la salida sea predecible y evita desperdiciar una tarea.

4. Imagen demasiado grande o demasiado pequeña

Las imágenes fijas de altísima resolución (por ejemplo, salida de cámara de 8K) consumen ancho de banda y pueden ser rechazadas o reducidas; las miniaturas extremadamente pequeñas dejan al modelo casi sin contenido para animar. Normaliza la imagen a una dimensión de lado largo razonable como parte de tu paso previo a la carga.

Pasar un archivo local

Si el endpoint acepta cargas multipart para el campo de imagen, el patrón es:

curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -F "image=@./first-frame.jpg" \
  -F "duration=5" \
  -F "aspect_ratio=16:9"

Ten en cuenta que los campos numéricos se convierten en cadenas cuando se usa multipart. Consulta la referencia del endpoint para saber qué tipos de contenido se aceptan, y prefiere la forma de URL en canales de producción: mantiene los archivos binarios grandes completamente fuera de tu servidor de aplicaciones.

Establece la duración y la relación de aspecto

Estos dos campos influyen en el costo y la salida más que cualquier otra cosa en el cuerpo de la solicitud.

duration

duration está en segundos e indica la longitud del clip generado. También es el campo más directamente relacionado con la facturación: el precio en tiempo real se calcula en función de la duración de salida que solicitas, así que elígelo con cuidado en lugar de dejar el valor máximo por defecto. Consejos prácticos:

  • Comienza con la duración más corta que cuente tu historia. Un clip de 5 segundos es ideal para bucles, avances de productos o ganchos para redes sociales.
  • Usa duraciones más largas solo cuando la escena realmente necesite más tiempo; un primer fotograma estático animado durante mucho tiempo tiende a desviarse y perder coherencia.
  • Valida en el cliente: rechaza valores no enteros, cero, negativos y absurdamente grandes antes de que la solicitud salga de tu servicio.
if not isinstance(duration, int) or not 1 <= duration <= 8:
    raise ValueError("duration out of supported range")

Confirma el rango admitido actual en la referencia del endpoint y replica ese rango en tu lógica de validación; no codifiques las suposiciones de este artículo.

aspect_ratio

aspect_ratio es una cadena, por ejemplo "16:9", "9:16" o "1:1". Controla la geometría del fotograma de salida.

  • 16:9 para horizontal: YouTube, videos principales de sitios web, reproducción en escritorio.
  • 9:16 para vertical: Reels, Shorts, anuncios estilo TikTok.
  • 1:1 para feeds y miniaturas.

Dos reglas te evitarán problemas. Primero, haz que la imagen de origen coincida con la proporción solicitada: usar un primer fotograma vertical en una solicitud horizontal provocará un recorte que probablemente no deseas. Segundo, trata la proporción como una enumeración, no como texto libre: valídala contra una lista blanca para que errores tipográficos como "16x9" fallen rápidamente en tu código en lugar de después de un viaje de ida y vuelta.

Todo lo demás

Si el endpoint expone controles de generación adicionales, déjalos fuera de tu primera solicitud. Un cuerpo de solicitud mínimo y verificado es tu línea base; agrega un parámetro a la vez y compara la salida. Esta disciplina hace que sea evidente qué campo causó una regresión.

Implementa la misma solicitud en Python

A continuación se muestra la versión en Python del flujo de curl. Mantiene deliberadamente las dependencias al mínimo: requests más la biblioteca estándar.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def submit(image_url: str, duration: int = 5, aspect_ratio: str = "16:9") -> str:
    resp = requests.post(
        f"{BASE}/v1/pixverse-v6-max/image-to-video",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"image": image_url, "duration": duration, "aspect_ratio": aspect_ratio},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["id"]

def fetch(job_id: str) -> dict:
    resp = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30)
    resp.raise_for_status()
    return resp.json()

if __name__ == "__main__":
    job_id = submit("https://your-cdn.example.com/first-frame.jpg")
    print("submitted", job_id)

Algunas decisiones deliberadas que vale la pena adoptar:

  • Llama a raise_for_status() al enviar. Un 400 o 401 debe exponerse inmediatamente como una excepción, no convertirse en un KeyError cuando intentas leer ["id"] del cuerpo de respuesta de error.
  • Tiempos de espera explícitos. Sin un tiempo de espera, una conexión estancada dejará tu worker colgado indefinidamente.
  • Configuración leída del entorno. La URL base y la clave nunca están codificadas en el código.
  • Funciones auxiliares pequeñas y tipadas. submit devuelve una cadena de id de tarea; fetch devuelve un diccionario. Centralizar el análisis significa que un cambio de esquema requiere solo una línea de cambio.

Si prefieres httpx, simplemente reemplaza por httpx.post(...) y httpx.get(...); la llamada es idéntica en todo lo demás. Para cualquier cosa que se ejecute dentro de un manejador de solicitudes web, envía aquí y luego pasa el id de la tarea a un worker en segundo plano, en lugar de bloquear la solicitud HTTP del usuario esperando la generación del video.

Consulta la tarea asíncrona hasta que se complete

La consulta periódica es la parte que la mayoría de los tutoriales pasa por alto y la fuente de la mayoría de los incidentes. El bucle en sí es corto; la disciplina a su alrededor es lo que importa.

def wait_for_video(job_id: str, timeout: int = 600, interval: int = 5) -> str:
    deadline = time.time() + timeout
    while time.time() < deadline:
        job = fetch(job_id)
        status = job.get("status")
        if status == "completed":
            return job["output"]["video_url"]
        if status in ("failed", "cancelled"):
            raise RuntimeError(f"job {job_id} ended as {status}: {job.get('error')}")
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} did not finish within {timeout}s")

Puntos clave codificados arriba:

  • Establece siempre una fecha límite. La generación de video es lenta; un bucle sin límites se convierte en facturación sin límites y workers bloqueados. Diez minutos es un límite razonable para clips cortos; ajústalo según tu configuración de duración.
  • Distingue los estados terminales. Solo completed produce una URL. failed y cancelled también son terminales: detén la consulta y expón el campo de error.
  • Usa un intervalo razonable. Cada pocos segundos es suficiente. Saturar el endpoint de estado te hará alcanzar el límite de solicitudes y no te dirá nada nuevo.
  • Retroceso suave para tareas largas: aumenta el intervalo de 3 segundos a 10 segundos después del primer minuto. Esto reduce la carga sin agregarte ningún costo de latencia.
  • Persiste los ids de tarea. Guárdalos junto con tus propios registros para que, si el proceso se reinicia, puedas reanudar la consulta sin reenviar (y volver a pagar) la misma tarea.
  • Nunca consultes directamente desde el navegador con tu clave de API. Realiza la comprobación de estado a través de tu backend.

Cuando la tarea se complete, descarga el video en tu propio almacenamiento de inmediato en lugar de enlazar para siempre a la URL devuelta; las URL de los recursos generados no tienen garantía de ser permanentes.

Soluciona tareas fallidas y estancadas

Sigue esta lista de verificación en orden. Cada paso aísla una capa.

Errores de envío (la tarea nunca se creó)

  • 401 Unauthorized: la clave falta, está mal formada, ha sido revocada o está emparejada con el host incorrecto. Verifica que el encabezado sea exactamente Authorization: Bearer <key>, con un solo espacio en el medio, y que la variable de entorno no tenga saltos de línea adicionales.
  • 403 Forbidden: la clave es válida pero no está autorizada para este modelo o endpoint. Revisa la ruta del recurso carácter por carácter: pixverse-v6-max/image-to-video.
  • 400 Bad Request: tu JSON está mal formado o algún campo no es válido. Decodifica el cuerpo de respuesta de error; generalmente señalará el campo problemático. Culpables comunes: duration como cadena en lugar de número, "16x9" en lugar de "16:9", falta de image.
  • Errores de validación tipo 422: el campo existe pero está fuera de rango. Consulta la referencia del endpoint en lugar de adivinar.
  • 429 Too Many Requests: estás enviando demasiado rápido. Pon en cola los envíos y reintenta con retroceso exponencial y jitter; nunca reintentes en un bucle ajustado.

Fallos de ejecución (la tarea se creó pero no tuvo éxito)

  • Estado failed con un error relacionado con la imagen: la obtención de la URL de origen falló después del envío. Esta es la clásica trampa de "funciona en mi navegador": la URL requiere cookies, referrer o una lista blanca de IP. Vuelve a alojar la imagen públicamente.
  • Estado failed con un error de contenido o validación: la imagen de origen fue rechazada por razones técnicas (formato, geometría, tamaño). Transcodifica, redimensiona y vuelve a recortar a la relación de aspecto declarada.
  • La tarea permanece en cola o en proceso después de tu fecha límite: primero confirma que estás leyendo el id de tarea correcto (los errores de copiar y pegar son sorprendentemente comunes). Luego verifica si el estado realmente no ha cambiado o si tu consulta está llegando a la URL base incorrecta. Si realmente está estancada, cancélala y vuelve a enviarla una vez si la API lo permite; reenviar repetidamente en silencio es exactamente cómo desaparece el presupuesto.

Un hábito que ahorra tiempo

Registra el id de solicitud completo, el id de tarea, el estado HTTP y el cuerpo de respuesta para cada llamada, y redacta las claves. Cuando algo falla a las dos de la mañana, un id de solicitud es la diferencia entre una solución de cinco minutos y una hora de conjeturas. Comienza con el cuerpo de solicitud mínimo y verificado, agrega un parámetro a la vez, y casi nunca necesitarás esta lista de verificación.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API