- Quando usar Hunyuan Video Fast vs Padrão
- Passo 1: Obtenha sua Chave de API da Novita AI
- Passo 2: Endpoint e ID do Modelo
- Passo 3: Envie sua Primeira Requisição
- Passo 4: Consulte o Resultado do Vídeo
- Exemplo em Python
- Exemplo em cURL
- Parâmetros Principais
- Preços e Limites
- Solução de Problemas
- FAQ
- Artigos Recomendados
O Hunyuan Video Fast está disponível na Novita AI em POST https://api.novita.ai/v3/async/hunyuan-video-fast. É a variante otimizada para velocidade do modelo de base Hunyuan Video de código aberto da Tencent — reduz o tempo de geração em comparação com a versão padrão, ao custo de alguma fidelidade de movimento, tornando-o prático para pipelines de alto rendimento, iteração de prompts e fluxos de trabalho de teste onde a rapidez de retorno é mais importante que o pico de qualidade cinematográfica.
Como todas as APIs de vídeo assíncronas da Novita, ela retorna um task_id no envio e entrega a URL do vídeo quando a tarefa é concluída. Este guia cobre o endpoint, formato da requisição, exemplos funcionais em Python e cURL, e onde a variante rápida se encaixa em relação ao modelo padrão.
Quando usar Hunyuan Video Fast vs Padrão
A variante rápida é a escolha certa quando a rapidez de geração e o volume de requisições são mais importantes do que a qualidade visual máxima. O Hunyuan Video padrão produz movimentos de maior fidelidade e melhor aderência ao prompt por geração. A variante rápida reduz esse tempo significativamente — útil para:
- Iteração de prompts — testar muitas variações de forma barata antes de se comprometer com uma renderização de qualidade total
- Pipelines de alto rendimento — geração em lote de conteúdo onde a latência por clipe afeta diretamente a taxa de transferência
- Testes e revisão interna — obter resultados compartilháveis rapidamente, depois mudar para o padrão na entrega final
- Aplicações de baixa latência — fluxos de trabalho de produção com orçamentos de tempo de resposta apertados
Se a qualidade de saída é a principal restrição — transmissão, entrega final ou movimento fotorrealista — use o endpoint Hunyuan Video padrão.
Passo 1: Obtenha sua Chave de API da Novita AI
Cadastre-se em novita.ai e gere uma chave de API na página de gerenciamento de chaves. Novas contas recebem créditos gratuitos. Armazene a chave como uma variável de ambiente — nunca a codifique diretamente em arquivos fonte.
export NOVITA_API_KEY="sua_chave_api_aqui"
Passo 2: Endpoint e ID do Modelo
| Campo | Valor |
|---|---|
| Endpoint de envio | POST https://api.novita.ai/v3/async/hunyuan-video-fast |
| Obtenção de resultado | GET https://api.novita.ai/v3/async/task-result?task_id=<id> |
| Cabeçalho de autenticação | Authorization: Bearer $NOVITA_API_KEY |
| Content-Type | application/json |
Referência oficial da API: novita.ai/docs/api-reference/model-apis-hunyuan-video-fast
Passo 3: Envie sua Primeira Requisição
Envie uma requisição de geração com seu prompt e configurações de saída:
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": "Uma raposa vermelha correndo por uma floresta nevada ao amanhecer, câmera lenta, plano aberto cinematográfico",
"negative_prompt": "borrado, baixa qualidade, distorcido, marca d'água",
"width": 1280,
"height": 720,
"seed": -1
}'
A API retorna um task_id imediatamente:
{
"task_id": "hunyuan-fast-abc123"
}
O vídeo não está nesta resposta — armazene o task_id e use-o no próximo passo.
Passo 4: Consulte o Resultado do Vídeo
curl -s "https://api.novita.ai/v3/async/task-result?task_id=hunyuan-fast-abc123" \
-H "Authorization: Bearer $NOVITA_API_KEY"
Continue consultando até que task_status seja TASK_STATUS_SUCCEED:
{
"task_status": "TASK_STATUS_SUCCEED",
"videos": [
{
"video_url": "https://cdn.novitai.com/output/...",
"video_url_ttl": 3600,
"video_type": "mp4"
}
]
}
Baixe ou armazene video_url prontamente — ela expira após video_url_ttl segundos.
Valores de Status da Tarefa
| Status | Significado |
|---|---|
TASK_STATUS_QUEUED |
Requisição aceita, aguardando execução |
TASK_STATUS_PROCESSING |
Geração em andamento |
TASK_STATUS_SUCCEED |
Completo — URL do vídeo disponível em videos[0].video_url |
TASK_STATUS_FAILED |
Geração falhou — verifique a resposta para o motivo da falha |
Exemplo em 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"Tarefa falhou: {data}")
time.sleep(interval)
raise TimeoutError(f"Tarefa {task_id} não concluiu em {timeout}s")
if __name__ == "__main__":
task_id = submit_video(
prompt="Uma raposa vermelha correndo por uma floresta nevada ao amanhecer, câmera lenta, plano aberto cinematográfico",
negative_prompt="borrado, baixa qualidade, distorcido, marca d'água",
width=1280,
height=720,
)
print(f"Tarefa enviada: {task_id}")
result = poll_result(task_id)
for video in result.get("videos", []):
print(f"URL do vídeo (expira em {video['video_url_ttl']}s): {video['video_url']}")
Exemplo em cURL
# Passo 1: Envie a requisição de geração
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": "Um timelapse de um horizonte urbano transitando do entardecer para a noite, cinematográfico",
"negative_prompt": "borrado, baixa qualidade, distorcido",
"width": 1280,
"height": 720,
"seed": 42
}' | jq -r '.task_id')
echo "Task ID: $TASK_ID"
# Passo 2: Consulte até concluir
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 "Falhou: $RESULT"
break
fi
echo "Status: $STATUS — aguardando..."
sleep 5
done
Parâmetros Principais
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
prompt |
string | Sim | Descrição textual da cena, assunto, movimento e estilo do vídeo |
negative_prompt |
string | Não | Elementos a evitar na saída (ex.: “borrado, baixa qualidade”) |
width |
integer | Não | Largura da saída em pixels — verifique a documentação da API para valores suportados |
height |
integer | Não | Altura da saída em pixels — combinada com width para definir a resolução |
seed |
integer | Não | Defina um inteiro fixo para reproduzir a mesma saída; -1 para aleatório |
Para a lista completa de parâmetros, incluindo opções de duração, restrições de resolução máxima e campos específicos do modelo, consulte a referência da API Hunyuan Video Fast.
Preços e Limites
Verifique os preços atuais por vídeo na página de modelos da Novita AI. O preço da geração de vídeo é tipicamente por clipe gerado e varia conforme resolução e duração. Verifique a página de preços antes de construir um modelo de custo para cargas de trabalho em produção.
Confirme os seguintes limites na documentação oficial antes de implantar:
- Comprimento máximo do prompt
- Valores de resolução suportados (combinações largura × altura)
- Duração máxima do vídeo em segundos
- Limites de taxa e teto de tarefas simultâneas por chave de API
A variante rápida geralmente custa menos por clipe que o modelo padrão devido ao menor tempo de computação — verifique a diferença atual na página de preços da Novita.
Solução de Problemas
401 Unauthorized — A chave de API está faltando, inválida ou expirou. Confirme que NOVITA_API_KEY está definida e que a chave está ativa no seu painel da Novita AI.
422 Unprocessable Entity — Falta um parâmetro obrigatório ou um valor está fora do intervalo. Confirme que prompt não está vazio e que os valores de width/height estão no conjunto suportado pela documentação da API.
Tarefa permanece em TASK_STATUS_PROCESSING — A geração ainda está em execução. A variante rápida completa mais rápido que a padrão, mas resoluções mais altas e durações maiores levam mais tempo. Aumente o tempo limite de consulta para saídas grandes.
video_url retorna 403 ou 404 — A URL expirou (video_url_ttl decorrido). Em produção, baixe ou transfira o vídeo imediatamente após TASK_STATUS_SUCCEED — não confie na URL hospedada como armazenamento permanente.
Problemas consistentes de qualidade em tipos específicos de prompt — Mude para uma abordagem de refinamento de prompt: descreva o assunto, ação, ângulo de câmera e estilo explicitamente. Adicione entradas em negative_prompt para artefatos comuns. Se a qualidade ainda for insuficiente para o caso de uso, avalie o endpoint Hunyuan Video padrão.
FAQ
Qual é o endpoint da Novita AI para Hunyuan Video Fast?
POST https://api.novita.ai/v3/async/hunyuan-video-fast. A API é assíncrona: envie uma requisição, receba um task_id, depois consulte GET https://api.novita.ai/v3/async/task-result?task_id=<id> até que task_status seja TASK_STATUS_SUCCEED.
Como Hunyuan Video Fast difere do Hunyuan Video padrão?
A variante rápida é otimizada para velocidade de geração — reduz o tempo desde o envio da tarefa até o vídeo concluído. A troca é que a fidelidade do movimento e a aderência fina ao prompt são menores que no modelo padrão. Use a variante rápida para iteração de prompts, trabalhos em lote de alto rendimento ou teste; use a padrão para saída de qualidade final.
Posso definir uma duração específica para o vídeo?
Verifique a referência da API para parâmetros de duração suportados. Algumas APIs de vídeo da Novita expõem um campo duration explícito; outras usam um padrão do modelo. Verifique antes de assumir um comprimento de clipe padrão.
Como reproduzir uma saída de vídeo específica?
Defina seed como um inteiro fixo. A mesma combinação de seed, prompt, width e height deve produzir saída consistente entre execuções.
O Hunyuan Video Fast suporta imagem para vídeo?
O Hunyuan Video Fast na Novita AI é um modelo de texto para vídeo. Para geração de imagem para vídeo na Novita, verifique os modelos I2V disponíveis como Kling, Vidu ou Wan na página de modelos da Novita.
Quanto custa o Hunyuan Video Fast na Novita AI?
Verifique os preços atuais em novita.ai/models. O preço por clipe para modelos de vídeo pode mudar; sempre verifique a página de preços antes de construir estimativas de custo de produção.
O Hunyuan Video Fast é adequado para pipelines de vídeo em produção?
Sim, com tratamento adequado. Projete seu pipeline em torno do envio assíncrono de tarefas, armazene o task_id para rastreamento de status, baixe o vídeo imediatamente após a conclusão (antes que video_url_ttl expire) e trate TASK_STATUS_FAILED com uma estratégia de repetição ou fallback.
