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
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:
- Haz
POSTde tu imagen y parámetros al endpoint de generación. - Recibe un identificador de tarea (normalmente con un estado inicial).
- Haz
GETdel estado de la tarea a intervalos hasta que se complete o falle. - 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(ohttpx) 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
Authorizationcomo 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 —
durationyaspect_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:9para horizontal: YouTube, videos principales de sitios web, reproducción en escritorio.9:16para vertical: Reels, Shorts, anuncios estilo TikTok.1:1para 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. Un400o401debe exponerse inmediatamente como una excepción, no convertirse en unKeyErrorcuando 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.
submitdevuelve una cadena de id de tarea;fetchdevuelve 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
completedproduce una URL.failedycancelledtambié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 exactamenteAuthorization: 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:durationcomo cadena en lugar de número,"16x9"en lugar de"16:9", falta deimage.- 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
failedcon 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
failedcon 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 →-
Tutorial
Guía práctica de gpt-6.2-sol: 5 usos de alto valor de los modelos de texto en el negocio
-
Tutorial
Guía práctica de gpt-6.2-astra: puntos clave de integración e implementación en 5 escenarios de texto de alto valor
Lista de verificación desde la perspectiva del desarrollador: de la selección de escenarios a la implementación en ingeniería
-
Tutorial
Casos prácticos de Tripo H3.1: 5 usos de alto valor y puntos clave de implementación
De texto a 3D a la reconstrucción multivista: elige el modo y los parámetros correctos según el escenario de negocio