Blog

Tutorial

Cómo usar pixverse-v6-max/text-to-video a través de la API de HiAPI: ejemplos de solicitudes ejecutables con curl y Python

Nov 13, 2026
Portada plana de un patrón de cesta tejida de espresso intenso, avena y latón que forma una cuadrícula similar a un telar.
En esta página

Qué hace este endpoint y cuándo usarlo

pixverse-v6-max/text-to-video es el endpoint de texto a video de HiAPI. Envías un prompt de texto que describe la escena deseada y el endpoint devuelve un video renderizado. Como la generación de video lleva tiempo, este endpoint es asíncrono: la primera solicitud no devuelve el video directamente, sino un identificador de tarea con el que consultas el progreso y obtienes el resultado final.

Este esquema de "solicitud—confirmación—sondeo" es el modelo mental central de todo el tutorial. El flujo interno siempre es el mismo:

  1. Envías una tarea de generación con el prompt y los parámetros.
  2. Recibes de inmediato un identificador de tarea.
  3. Consultas esa tarea hasta que informe que terminó (o falló).
  4. Descargas o incrustas la URL del video resultante.

Cuándo conviene usar este endpoint

Elige pixverse-v6-max/text-to-video cuando solo tengas una descripción y ningún material de origen, por ejemplo para crear un avance de producto a partir de un brief textual, generar clips de fondo para una aplicación o preparar previsualizaciones de storyboard. Si ya tienes una imagen y quieres animarla, eso corresponde a un flujo de imagen a video, no a este endpoint. Si prefieres que el modelo itere el prompt de forma conversacional, eso corresponde a otro modo de interacción. Este endpoint es la vía directa de generación única de texto a video.

Como la generación es asíncrona, también encaja en arquitecturas basadas en colas: un backend web recibe la solicitud del usuario, envía la tarea y luego un proceso trabajador la consulta y entrega el resultado más tarde. Ninguna parte del proceso de llamada se bloquea hasta que termine el renderizado completo.

Antes de empezar: autenticación y fundamentos de las solicitudes

Antes de escribir código, confirma tres cosas.

1. Una clave de API

Toda solicitud a HiAPI requiere autenticación con una clave de API. Trátala como una contraseña: no la confirmes en el repositorio de código, cárgala desde una variable de entorno y rótala de inmediato si se filtra. Los ejemplos siguientes la leen de HIAPI_API_KEY, así que expórtala primero en la shell:

export HIAPI_API_KEY="your_key_here"

2. La URL base correcta

Todas las solicitudes se envían a la URL base de la API de HiAPI más la ruta del endpoint. Usa la URL base que figure en tu cuenta de HiAPI en lugar de codificar un host tomado de un artículo de blog; si no estás seguro, consulta la referencia de la API en el panel. Los ejemplos siguientes usan $HIAPI_BASE_URL como marcador de posición para ese valor.

3. Convenciones JSON

Tanto el envío como la consulta de estado se basan en JSON sobre HTTPS:

  • Envía Content-Type: application/json en cada solicitud con cuerpo.
  • Envía Authorization: Bearer $HIAPI_API_KEY en cada solicitud, incluidas las consultas de estado.
  • Espera JSON en las respuestas, también en caso de error: lee el cuerpo de la respuesta de error, no solo el código de estado HTTP.

Comprobación rápida de salud

Si tienes disponible algún endpoint ligero (por ejemplo, una ruta de modelos o de cuenta), llámalo una vez antes de tocar el endpoint de video. Un 200 ahí demuestra que tu clave, la URL base y el formato de las cabeceras son correctos, lo que elimina tres variables en la depuración posterior.

Una solicitud curl ejecutable

Esta es la llamada de envío completa. La ruta del endpoint es pixverse-v6-max/text-to-video; el cuerpo lleva tu prompt y los parámetros de generación.

curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "De noche, un callejón de neón empapado por la lluvia, travelling lento, aspecto cinematográfico",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

Explicación campo por campo

  • prompt: la descripción textual. Sé explícito sobre el sujeto, el movimiento, el movimiento de cámara y la atmósfera. Es la palanca más importante para la calidad del resultado.
  • duration: la duración solicitada del clip. Consulta la sección de duración y relación de aspecto más abajo.
  • aspect_ratio: la relación de aspecto de salida, por ejemplo 16:9, 9:16 o 1:1.

Qué devuelve

Un envío correcto devuelve un objeto JSON que contiene un identificador de tarea, es decir, el identificador que usarás para el sondeo. Consulta la referencia de la API para el nombre exacto del campo; en este tutorial lo llamamos task_id. Guárdalo:

TASK_ID=$(curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"De noche, un callejón de neón empapado por la lluvia, travelling lento, aspecto cinematográfico","duration":5,"aspect_ratio":"16:9"}' \
  | python -c 'import sys,json; print(json.load(sys.stdin)["task_id"])')
echo "$TASK_ID"

Fíjate en lo que la respuesta no contiene: el video. La generación se ejecuta en segundo plano. Trata la respuesta del envío como un acuse de recibo, no como el resultado.

La misma solicitud en Python

La versión en Python corresponde exactamente a la llamada curl. Usamos requests por brevedad, pero httpx o urllib funcionan igual: el único requisito son las mismas cabeceras y el mismo cuerpo JSON.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "prompt": "De noche, un callejón de neón empapado por la lluvia, travelling lento, aspecto cinematográfico",
    "duration": 5,
    "aspect_ratio": "16:9",
}

resp = requests.post(
    f"{BASE_URL}/pixverse-v6-max/text-to-video",
    headers=headers,
    json=payload,
    timeout=30,
)

if resp.status_code >= 400:
    # Imprime el cuerpo de la respuesta de error del servidor: suele indicar el campo problemático
    raise RuntimeError(f"submit failed {resp.status_code}: {resp.text}")

data = resp.json()
task_id = data["task_id"]
print("submitted:", task_id)

Puntos que vale la pena copiar

  • json=payload serializa automáticamente el cuerpo y establece el tipo de contenido. Si usas data=json.dumps(payload), conserva la cabecera explícita Content-Type.
  • Establecer un tiempo de espera del cliente al enviar evita que la conexión se quede colgada. No limita el tiempo de generación: esta ocurre en el servidor, que es justo la razón por la que hay que sondear.
  • Comprueba el código de estado antes de parsear. El cuerpo de una respuesta 4xx suele dar más información que el propio código de estado; imprímelo.
  • Nunca registres la clave de API. Registra task_id en su lugar: se puede almacenar sin riesgo y es tu identificador de depuración.

Parámetros de duración y relación de aspecto

Estos dos campos son la causa más común de solicitudes rechazadas, así que conviene tratarlos con cuidado.

duration

duration establece la longitud solicitada del clip, en segundos. Los valores que puedes pedir están limitados al rango admitido por el endpoint; enviar un valor fuera de ese rango normalmente produce un error de validación de parámetros en lugar de truncar el clip en silencio. Elige entre los valores admitidos documentados en la referencia de la API y mantenlo como entero. Cuanto más largo sea el clip, más tardará el renderizado, así que durante el desarrollo prioriza la duración más corta admitida: lo que estás validando es la cadena de proceso, no la calidad artística.

aspect_ratio

aspect_ratio es una cadena con la forma W:H. Haz que coincida con el lugar donde se mostrará finalmente el video:

  • 16:9: horizontal: franjas principales de sitios web, reproductores estilo YouTube, fondos de escritorio.
  • 9:16: vertical: feeds de videos cortos y stories en móvil.
  • 1:1: cuadrado: diseños de cuadrícula y miniaturas.

Elegir mal la forma aquí es barato de corregir, pero caro de descubrir demasiado tarde: volver a renderizar consume otro ciclo completo de generación, así que conviene decidir el destino de visualización antes de enviar.

Qué revisar cuando se rechaza

  • Desajuste de tipos: duration escrito como cadena ("5") en lugar de número, o aspect_ratio escrito como dos números. Mantén duration como valor numérico y aspect ratio como cadena.
  • Valores no admitidos: duración o relación fuera del rango documentado. Compáralos uno a uno con la lista de referencia.
  • Nombres de campos: errores tipográficos como aspectRatio o durationSeconds, en el mejor de los casos, se tratan silenciosamente como campos desconocidos. Copia los nombres de campo desde la documentación de referencia.

Método rápido para localizar el campo problemático: reenvía primero solo con prompt y luego vuelve a añadir los parámetros uno a uno. El primer rechazo te indicará el campo problemático.

Sondear la tarea asíncrona hasta que el video esté listo

El sondeo es un bucle que sigue tres reglas: comprobar el estado, dormir y detenerse en un estado terminal. Añade además un límite superior para evitar que una tarea atascada gire indefinidamente.

import time
import requests

def wait_for_video(task_id, base_url, api_key, timeout=600):
    headers = {"Authorization": f"Bearer {api_key}"}
    url = f"{base_url}/tasks/{task_id}"   # Consulta la ruta de estado en la referencia de la API
    deadline = time.time() + timeout
    delay = 2

    while time.time() < deadline:
        r = requests.get(url, headers=headers, timeout=30)
        r.raise_for_status()
        task = r.json()
        status = task["status"]

        if status == "succeeded":
            return task["result"]["video_url"]
        if status == "failed":
            raise RuntimeError(f"generation failed: {task.get('error')}")

        time.sleep(delay)
        delay = min(delay * 1.5, 15)   # Retroceso moderado con límite superior

    raise TimeoutError(f"task {task_id} not finished in {timeout}s")

Por qué importa el retroceso

Sondear una tarea de generación que tarda un minuto a intervalos fijos de un segundo desperdicia decenas de solicitudes. Empieza con un intervalo pequeño y auméntalo de forma gradual: el factor con límite superior anterior se estabiliza en un intervalo cómodo sin saturar la API con frecuencia. Si vas a ejecutar muchas tareas, una cola con un único proceso trabajador de sondeo es más amable que un bucle por solicitud.

Manejar el resultado

Cuando la tarea termina correctamente, la respuesta incluye la URL del video. Obténla a tiempo y, si el resultado debe conservarse, cópiala a tu propio almacenamiento: las URL firmadas no son válidas para siempre. Antes de entregar el archivo al usuario, comprueba el tipo de contenido y el tamaño al descargarlo, y registra el task_id junto con el activo almacenado, de modo que cualquier problema futuro pueda rastrearse hasta el registro exacto de generación.

Solucionar errores comunes

Cuando una llamada falla, recorre esta lista punto por punto. La mayoría de los fallos pertenecen a una de las cuatro categorías siguientes.

Autenticación y acceso

  • 401 / no autorizado: la clave falta, tiene un formato incorrecto o no se envió. Confirma que la cabecera sea exactamente Authorization: Bearer <key> y que la variable de entorno tenga realmente asignado un valor en la shell o el proceso que realiza la llamada.
  • 403 / prohibido: la clave es válida, pero no tiene permiso para acceder a este endpoint. Revisa los ámbitos de permiso de la clave en el panel.

Validación de la solicitud

  • 400 / 422: JSON mal formado o valor de campo incorrecto. Imprime el cuerpo completo de la respuesta de error; normalmente indica el campo. Vuelve a revisar el tipo de duration y el formato de cadena de aspect_ratio.
  • 404 al enviar: ruta del endpoint incorrecta. Confirma que la ruta sea exactamente pixverse-v6-max/text-to-video y que tu URL base no tenga segmentos de ruta duplicados ni faltantes.

Fallos a nivel de tarea

  • Estado failed: la tarea se aceptó pero la generación falló. Lee el mensaje de error de la tarea; permite distinguir entre rechazo de contenido y fallo interno. Un prompt rechazado es un problema del prompt, no de la API: modifícalo y vuelve a enviar.
  • Atascado en estado de ejecución: establece una fecha límite para el sondeo y trata el tiempo de espera agotado como un fallo que debes manejar, no como una excepción que haga caer el servicio.

Problemas operativos

  • 429 / límite de peticiones alcanzado: hay demasiados envíos o sondeos en curso. Reduce la concurrencia y respeta cualquier indicación de reintento de la respuesta.
  • Tiempo de espera de conexión al enviar: problema de red o de proxy, no de generación. Reintenta el envío con retroceso, pero solo si puedes tolerar la posible creación de tareas duplicadas.
  • 404 de la URL del video al descargar: la URL ha caducado. Vuelve a obtener el resultado de la tarea en lugar de reutilizar una URL antigua.

Un hábito repetible

En cada fallo registra tres valores: el código de estado HTTP, el cuerpo de la respuesta y, si existe, el task_id. Esos tres convierten "se rompió" en "se rompió aquí", y esa es la única clave para depurar más rápido.

Qué hacer a continuación

Ya tienes el ciclo completo: autenticarte, enviar, obtener el identificador de tarea, sondear con retroceso y obtener el resultado. Para pasar a producción, encapsula el envío y el sondeo en una pequeña clase cliente, almacena task_id y el prompt junto con cada activo para poder rastrearlo, y mueve el sondeo a un proceso trabajador en segundo plano para que las solicitudes orientadas al usuario nunca se bloqueen por el renderizado.

A continuación, explora los endpoints adyacentes en la referencia de HiAPI: imagen a video para animar una imagen fija existente, y el modo de interacción iterativa de prompts para pulir el estilo visual antes de comprometerte con una generación completa. La forma de las solicitudes que aprendiste aquí se traslada casi sin cambios.

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