- 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: 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 base Hunyuan Video de código abierto 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 staging donde la velocidad de respuesta importa más que la calidad cinematográfica máxima.
Como todas las API 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 funcionales 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 velocidad de generación y el volumen de solicitudes importan más que la calidad visual máxima. Hunyuan Video estándar produce movimientos 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 un render de calidad completa.
- Pipelines de alto rendimiento — generación de contenido por lotes donde la latencia por clip afecta directamente el rendimiento.
- Staging 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), usa el endpoint estándar de Hunyuan Video en su lugar.
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 una 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 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: 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 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 |
Generación fallida: verifica 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"Tarea fallida: {data}")
time.sleep(interval)
raise TimeoutError(f"La tarea {task_id} no se completó en {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 tarea: $TASK_ID"
# Paso 2: Consultar 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 "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 combina 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, incluyendo opciones de duración, restricciones de resolución máxima y campos específicos 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 videos 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 velocidad 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, es invá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 del rango permitido. Confirma que prompt no esté vacío y que los valores de width/height estén dentro del conjunto admitido según la documentación de la API.
La tarea permanece en TASK_STATUS_PROCESSING — La generación aún está en ejecución. La variante rápida se 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 de forma explícita. Añade 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.
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 de Hunyuan Video 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 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 staging; usa la estándar para salidas 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 API de video de Novita exponen un campo duration explícito; otras usan un valor predeterminado del modelo. Verifica antes de asumir una duración de clip por defecto.
¿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 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. El precio por clip para modelos de video puede cambiar; consulta siempre la página de precios antes de elaborar 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 completarse (antes de que expire video_url_ttl) y maneja TASK_STATUS_FAILED con una estrategia de reintento o respaldo.
