- Cuándo usar Hunyuan Video Fast vs. Estándar
- Paso 1: Obtén tu clave API de Novita AI
- Paso 2: Endpoint e ID del modelo
- Paso 3: Envía tu primera solicitud
- Paso 4: Consulta el resultado del video
- Ejemplo en Python
- Ejemplo en cURL
- Parámetros clave
- Precios y límites
- Solución de problemas
- Preguntas frecuentes
- Artículos recomendados
Hunyuan Video Fast está disponible en Novita AI en POST https://api.novita.ai/v3/async/hunyuan-video-fast. Es la variante optimizada para velocidad del modelo de código abierto Hunyuan Video de Tencent: reduce el tiempo de generación en comparación con la versión estándar, a costa de cierta fidelidad de movimiento, lo que la hace práctica para procesos de alto rendimiento, iteración de prompts y flujos de trabajo de preparación donde la velocidad de respuesta es más importante que la calidad cinematográfica máxima.
Como todas las APIs de video asíncronas de Novita, devuelve un task_id al enviar la solicitud y entrega la URL del video una vez que la tarea se completa. Esta guía cubre el endpoint, el formato de la solicitud, ejemplos prácticos en Python y cURL, y dónde encaja la variante rápida en comparación con el modelo estándar.
Cuándo usar Hunyuan Video Fast vs. Estándar
La variante rápida es la opción adecuada cuando la velocidad de generación y el volumen de solicitudes importan más que la calidad visual máxima. Hunyuan Video estándar produce movimiento de mayor fidelidad y mejor adherencia al prompt por generación. La variante rápida reduce ese tiempo significativamente; útil para:
- Iteración de prompts — probar muchas variaciones de forma económica antes de comprometerse con una renderización de calidad completa.
- Procesos de alto rendimiento — generación de contenido por lotes donde la latencia por clip afecta directamente el rendimiento.
- Preparación y revisión interna — obtener resultados compartibles rápidamente, luego cambiar al estándar para la entrega final.
- Aplicaciones de baja latencia — flujos de trabajo de producción con presupuestos de tiempo de respuesta ajustados.
Si la calidad del resultado es la principal limitación (transmisión, entrega final o movimiento fotorrealista), usa el endpoint estándar de Hunyuan Video en su lugar.
Paso 1: Obtén tu clave API de Novita AI
Regístrate en novita.ai y genera una clave API desde la página de gestión de claves. Las cuentas nuevas reciben créditos gratuitos. Almacena la clave como variable de entorno; nunca la codifiques directamente en los archivos fuente.
export NOVITA_API_KEY="tu_clave_api_aqui"
Paso 2: Endpoint e ID del modelo
| Campo | Valor |
|---|---|
| Endpoint de envío | POST https://api.novita.ai/v3/async/hunyuan-video-fast |
| Obtención de resultado | GET https://api.novita.ai/v3/async/task-result?task_id=<id> |
| Cabecera de autenticación | Authorization: Bearer $NOVITA_API_KEY |
| Content-Type | application/json |
Referencia oficial de la API: novita.ai/docs/api-reference/model-apis-hunyuan-video-fast
Paso 3: Envía tu primera solicitud
Envía una solicitud de generación con tu prompt y configuración de salida:
curl -s -X POST https://api.novita.ai/v3/async/hunyuan-video-fast \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Un zorro rojo corriendo por un bosque nevado al amanecer, cámara lenta, plano general cinematográfico",
"negative_prompt": "borroso, baja calidad, distorsionado, marca de agua",
"width": 1280,
"height": 720,
"seed": -1
}'
La API devuelve un task_id de inmediato:
{
"task_id": "hunyuan-fast-abc123"
}
El video no está en esta respuesta; guarda el task_id y úsalo en el siguiente paso.
Paso 4: Consulta el resultado del video
curl -s "https://api.novita.ai/v3/async/task-result?task_id=hunyuan-fast-abc123" \
-H "Authorization: Bearer $NOVITA_API_KEY"
Sigue consultando hasta que task_status sea TASK_STATUS_SUCCEED:
{
"task_status": "TASK_STATUS_SUCCEED",
"videos": [
{
"video_url": "https://cdn.novitai.com/output/...",
"video_url_ttl": 3600,
"video_type": "mp4"
}
]
}
Descarga o almacena video_url rápidamente; caduca después de video_url_ttl segundos.
Valores del estado de la tarea
| Estado | Significado |
|---|---|
TASK_STATUS_QUEUED |
Solicitud aceptada, esperando para ejecutarse |
TASK_STATUS_PROCESSING |
Generación en curso |
TASK_STATUS_SUCCEED |
Completada: la URL del video está disponible en videos[0].video_url |
TASK_STATUS_FAILED |
Generación fallida: consulta la respuesta para conocer el motivo del fallo |
Ejemplo en Python
import os
import time
import requests
API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def submit_video(
prompt: str,
negative_prompt: str = "",
width: int = 1280,
height: int = 720,
seed: int = -1,
) -> str:
payload = {
"prompt": prompt,
"negative_prompt": negative_prompt,
"width": width,
"height": height,
"seed": seed,
}
resp = requests.post(
f"{BASE_URL}/v3/async/hunyuan-video-fast",
headers=HEADERS,
json=payload,
)
resp.raise_for_status()
return resp.json()["task_id"]
def poll_result(task_id: str, interval: int = 5, timeout: int = 300) -> dict:
deadline = time.time() + timeout
while time.time() < deadline:
resp = requests.get(
f"{BASE_URL}/v3/async/task-result",
headers=HEADERS,
params={"task_id": task_id},
)
resp.raise_for_status()
data = resp.json()
status = data.get("task_status", "")
if status == "TASK_STATUS_SUCCEED":
return data
if status == "TASK_STATUS_FAILED":
raise RuntimeError(f"Task failed: {data}")
time.sleep(interval)
raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")
if __name__ == "__main__":
task_id = submit_video(
prompt="Un zorro rojo corriendo por un bosque nevado al amanecer, cámara lenta, plano general cinematográfico",
negative_prompt="borroso, baja calidad, distorsionado, marca de agua",
width=1280,
height=720,
)
print(f"Tarea enviada: {task_id}")
result = poll_result(task_id)
for video in result.get("videos", []):
print(f"URL del video (caduca en {video['video_url_ttl']}s): {video['video_url']}")
Ejemplo en cURL
# Paso 1: Enviar la solicitud de generación
TASK_ID=$(curl -s -X POST https://api.novita.ai/v3/async/hunyuan-video-fast \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Un lapso de tiempo de un horizonte urbano que transita del atardecer a la noche, cinematográfico",
"negative_prompt": "borroso, baja calidad, distorsionado",
"width": 1280,
"height": 720,
"seed": 42
}' | jq -r '.task_id')
echo "ID de la tarea: $TASK_ID"
# Paso 2: Consultar hasta que se complete
while true; do
RESULT=$(curl -s "https://api.novita.ai/v3/async/task-result?task_id=$TASK_ID" \
-H "Authorization: Bearer $NOVITA_API_KEY")
STATUS=$(echo "$RESULT" | jq -r '.task_status')
if [ "$STATUS" = "TASK_STATUS_SUCCEED" ]; then
echo "$RESULT" | jq -r '.videos[0].video_url'
break
elif [ "$STATUS" = "TASK_STATUS_FAILED" ]; then
echo "Falló: $RESULT"
break
fi
echo "Estado: $STATUS — esperando..."
sleep 5
done
Parámetros clave
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
prompt |
string | Sí | Descripción textual de la escena del video, sujeto, movimiento y estilo |
negative_prompt |
string | No | Elementos a evitar en la salida (ej., “borroso, baja calidad”) |
width |
integer | No | Ancho de salida en píxeles; consulta la documentación de la API para valores admitidos |
height |
integer | No | Alto de salida en píxeles; se empareja con width para definir la resolución |
seed |
integer | No | Establece un entero fijo para reproducir la misma salida; -1 para aleatorio |
Para la lista completa de parámetros, incluidas las opciones de duración, las restricciones de resolución máxima y cualquier campo específico del modelo, consulta la referencia de la API de Hunyuan Video Fast.
Precios y límites
Verifica los precios actuales por video en la página de modelos de Novita AI. El precio de generación de video suele ser por clip generado y varía según la resolución y la duración. Consulta la página de precios antes de crear un modelo de costos para cargas de trabajo de producción.
Confirma los siguientes límites en la documentación oficial antes de implementar:
- Longitud máxima de caracteres del prompt
- Valores de resolución admitidos (combinaciones ancho × alto)
- Duración máxima del video en segundos
- Límites de velocidad y límites de tareas simultáneas por clave API
La variante rápida suele costar menos por clip que el modelo estándar debido al menor tiempo de cómputo; verifica la diferencia actual en la página de precios de Novita.
Solución de problemas
401 Unauthorized — La clave API falta, no es válida o ha caducado. Confirma que NOVITA_API_KEY esté configurada y que la clave esté activa en tu panel de Novita AI.
422 Unprocessable Entity — Falta un parámetro obligatorio o un valor está fuera de rango. Confirma que prompt no esté vacío y que los valores de width/height estén en el conjunto admitido según la documentación de la API.
La tarea permanece en TASK_STATUS_PROCESSING — La generación aún se está ejecutando. La variante rápida completa más rápido que la estándar, pero las resoluciones más altas y las duraciones más largas requieren más tiempo. Aumenta el tiempo de espera de tu consulta para salidas grandes.
video_url devuelve 403 o 404 — La URL ha caducado (ha transcurrido video_url_ttl). En producción, descarga o transfiere el video inmediatamente después de TASK_STATUS_SUCCEED; no confíes en la URL alojada como almacenamiento permanente.
Problemas de calidad consistentes en tipos de prompt específicos — Cambia a un enfoque de refinamiento del prompt: describe el sujeto, la acción, el ángulo de cámara y el estilo explícitamente. Agrega entradas de negative_prompt para artefactos comunes. Si la calidad sigue siendo insuficiente para el caso de uso, evalúa el endpoint estándar de Hunyuan Video.
Preguntas frecuentes
¿Cuál es el endpoint de Novita AI para Hunyuan Video Fast?
POST https://api.novita.ai/v3/async/hunyuan-video-fast. La API es asíncrona: envía una solicitud, recibe un task_id, luego consulta GET https://api.novita.ai/v3/async/task-result?task_id=<id> hasta que task_status sea TASK_STATUS_SUCCEED.
¿En qué se diferencia Hunyuan Video Fast del estándar de Hunyuan Video?
La variante rápida está optimizada para la velocidad de generación: reduce el tiempo desde el envío de la tarea hasta el video completado. La contrapartida es que la fidelidad del movimiento y la adherencia precisa al prompt son menores que en el modelo estándar. Usa la variante rápida para iteración de prompts, trabajos por lotes de alto rendimiento o preparación; usa la estándar para resultados de calidad final.
¿Puedo establecer una duración específica del video?
Consulta la referencia de la API para conocer los parámetros de duración admitidos. Algunas APIs de video de Novita exponen un campo duration explícito; otras usan un valor predeterminado del modelo. Verifica antes de asumir una longitud de clip predeterminada.
¿Cómo puedo reproducir una salida de video específica?
Establece seed en un entero fijo. La misma combinación de seed, prompt, width y height debería producir una salida consistente en diferentes ejecuciones.
¿Hunyuan Video Fast admite la conversión de imagen a video?
Hunyuan Video Fast en Novita AI es un modelo de texto a video. Para generar video a partir de imágenes en Novita, consulta los modelos I2V disponibles, como Kling, Vidu o Wan, en la página de modelos de Novita.
¿Cuánto cuesta Hunyuan Video Fast en Novita AI?
Verifica los precios actuales en novita.ai/models. El precio por clip de los modelos de video puede cambiar; siempre consulta la página de precios antes de hacer estimaciones de costos de producción.
¿Es Hunyuan Video Fast adecuado para procesos de video en producción?
Sí, con el manejo adecuado. Diseña tu proceso en torno al envío de tareas asíncronas, almacena el task_id para el seguimiento del estado, descarga el video inmediatamente después de la finalización (antes de que expire video_url_ttl) y maneja TASK_STATUS_FAILED con una estrategia de reintento o respaldo.
