- Cuándo usar Hunyuan Video Fast vs Estándar
- Paso 1: Obtén tu clave de API de Novita AI
- Paso 2: Endpoint e ID del modelo
- Paso 3: Envía tu primera solicitud
- Paso 4: Sondea para obtener el resultado del video
- Ejemplo en Python
- Ejemplo con cURL
- Parámetros clave
- Precios y límites
- Solución de problemas
- FAQ
- 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 en 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 pipelines de alto rendimiento, iteración de prompts y flujos de trabajo de preparación donde la rapidez de respuesta importa más 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 solicitud, ejemplos prácticos en Python y cURL, y dónde encaja la variante rápida frente al modelo estándar.
Cuándo usar Hunyuan Video Fast vs Estándar
La variante rápida es la opción adecuada cuando la rapidez 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.
- Pipelines 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 de salida es la principal restricción (transmisión, entrega final o movimiento fotorrealista), utiliza en su lugar el endpoint estándar de Hunyuan Video.
Paso 1: Obtén tu clave de API de Novita AI
Regístrate en novita.ai y genera una clave de 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 resultados | 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": "A red fox running through a snowy forest at dawn, slow motion, cinematic wide shot",
"negative_prompt": "blurry, low quality, distorted, watermark",
"width": 1280,
"height": 720,
"seed": -1
}'
La API devuelve un task_id inmediatamente:
{
"task_id": "hunyuan-fast-abc123"
}
El video no está en esta respuesta; guarda el task_id y úsalo en el siguiente paso.
Paso 4: Sondea para obtener 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 sondeando 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 de inmediato; caduca después de video_url_ttl segundos.
Valores de estado de la tarea
| Estado | Significado |
|---|---|
TASK_STATUS_QUEUED |
Solicitud aceptada, esperando ejecución |
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 |
Error en la generación: verifica la respuesta para obtener 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="A red fox running through a snowy forest at dawn, slow motion, cinematic wide shot",
negative_prompt="blurry, low quality, distorted, watermark",
width=1280,
height=720,
)
print(f"Task submitted: {task_id}")
result = poll_result(task_id)
for video in result.get("videos", []):
print(f"Video URL (expires in {video['video_url_ttl']}s): {video['video_url']}")
Ejemplo con 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": "A timelapse of a city skyline transitioning from dusk to night, cinematic",
"negative_prompt": "blurry, low quality, distorted",
"width": 1280,
"height": 720,
"seed": 42
}' | jq -r '.task_id')
echo "Task ID: $TASK_ID"
# Paso 2: Sondeo hasta completar
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 "Failed: $RESULT"
break
fi
echo "Status: $STATUS — waiting..."
sleep 5
done
Parámetros clave
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
prompt |
string | Sí | Descripción textual de la escena, sujeto, movimiento y estilo del video |
negative_prompt |
string | No | Elementos a evitar en la salida (ej.: “blurry, low quality”) |
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 combina con width para establecer 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 máximas de resolución 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 construir 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 tasa y límites de tareas concurrentes por clave de 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 de API falta, no es válida o ha expirado. 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 del rango permitido. Confirma que prompt no esté vacío y que los valores de width/height estén dentro del conjunto admitido en la documentación de la API.
La tarea permanece en TASK_STATUS_PROCESSING — La generación aún está en curso. La variante rápida completa más rápido que la estándar, pero las resoluciones más altas y duraciones más largas requieren más tiempo. Aumenta el tiempo de espera de sondeo para salidas grandes.
video_url devuelve 403 o 404 — La URL ha caducado (video_url_ttl ha transcurrido). En producción, descarga o transfiere el video inmediatamente después de TASK_STATUS_SUCCEED; no dependas de 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 explícitamente el sujeto, la acción, el ángulo de cámara y el estilo. Agrega entradas en 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.
FAQ
¿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 sondea 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?
La variante rápida está optimizada para la velocidad de generación: reduce el tiempo desde el envío de la tarea hasta la obtención del video completo. La compensación es que la fidelidad del movimiento y la adherencia fina 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 salida de calidad final.
¿Puedo establecer una duración específica para el video?
Consulta la referencia de la API para ver los parámetros de duración admitidos. Algunas APIs de video de Novita exponen un campo explícito duration; otras usan un valor predeterminado del modelo. Verifica antes de asumir una duración de clip predeterminada.
¿Cómo reproduzco 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 entre 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 generación de imagen a video 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. Los precios por clip para modelos de video pueden cambiar; siempre consulta la página de precios antes de hacer estimaciones de costos de producción.
¿Es Hunyuan Video Fast adecuado para pipelines de video en producción?
Sí, con el manejo adecuado. Diseña tu pipeline en torno al envío asíncrono de tareas, 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 alternativa.
