- Quando Usar o 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 base Hunyuan Video de código aberto da Tencent — ele 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 velocidade de resposta é mais importante que a qualidade cinematográfica máxima.
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 aborda o endpoint, o formato da requisição, exemplos funcionais em Python e cURL, e onde a variante rápida se encaixa em comparação com o modelo padrão.
Quando Usar o Hunyuan Video Fast vs Padrão
A variante rápida é a escolha certa quando o tempo de geração e o volume de requisições são mais importantes que a qualidade visual máxima. O Hunyuan Video padrão produz movimento com maior fidelidade e melhor aderência ao prompt por geração. A variante rápida reduz significativamente esse tempo — útil para:
- Iteração de prompts — testar muitas variações de forma econômica antes de se comprometer com uma renderização de qualidade total
- Pipelines de alto rendimento — geração de conteúdo em lote onde a latência por clipe afeta diretamente a taxa de transferência
- Testes e revisão interna — obter saída compartilhável rapidamente, depois mudar para o padrão para 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 padrão Hunyuan Video em vez disso.
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 de código.
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 |
| Recuperaçã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": "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
}'
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 |
Completa — 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"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']}")
Exemplo em cURL
# Passo 1: Enviar 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": "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"
# Passo 2: Consultar até 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 Principais
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
prompt |
string | Sim | Descrição textual da cena do vídeo, assunto, movimento e estilo |
negative_prompt |
string | Não | Elementos a evitar na saída (ex.: “blurry, low quality”) |
width |
integer | Não | Largura da saída em pixels — consulte a documentação da API para valores suportados |
height |
integer | Não | Altura da saída em pixels — pareada 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 máximas de resolução e quaisquer 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 de acordo com a resolução e duração. Verifique a página de preços antes de montar um modelo de custo para cargas de trabalho de produção.
Confirme os seguintes limites na documentação oficial antes de implantar:
- Tamanho máximo de caracteres do prompt
- Valores de resolução suportados (combinações largura × altura)
- Duração máxima do vídeo em segundos
- Limites de taxa e limite de tarefas concorrentes por chave de API
A variante rápida geralmente custa menos por clipe do que o modelo padrão devido ao tempo de computação reduzido — verifique a diferença atual na página de preços da Novita.
Solução de Problemas
401 Unauthorized — A chave de API está ausente, inválida ou expirou. Confirme se NOVITA_API_KEY está definida e se a chave está ativa no seu painel da Novita AI.
422 Unprocessable Entity — Um parâmetro obrigatório está faltando ou um valor está fora do intervalo. Confirme se prompt não está vazio e se os valores de width/height estão no conjunto suportado pela documentação da API.
A 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 polling 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 dependa da URL hospedada como armazenamento permanente.
Problemas de qualidade consistentes em tipos específicos de prompt — Mude para a abordagem de refinamento de prompt: descreva o assunto, ação, ângulo da 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 padrão do Hunyuan Video.
FAQ
Qual é o endpoint da Novita AI para o 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 o Hunyuan Video Fast difere do Hunyuan Video padrão?
A variante rápida é otimizada para velocidade de geração — ela reduz o tempo desde o envio da tarefa até o vídeo concluído. A contrapartida é que a fidelidade do movimento e a aderência refinada 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 testes; 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 explícito duration; outras usam um padrão do modelo. Verifique antes de assumir um comprimento de clipe padrão.
Como reproduzo 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 uma 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. Os preços por clipe para modelos de vídeo podem mudar; sempre verifique a página de preços antes de criar estimativas de custo de produção.
O Hunyuan Video Fast é adequado para pipelines de vídeo em produção?
Sim, com o tratamento adequado. Projete seu pipeline em torno do envio assíncrono de tarefas, armazene o task_id para monitoramento de status, baixe o vídeo imediatamente após a conclusão (antes que video_url_ttl expire) e lide com TASK_STATUS_FAILED com uma estratégia de repetição ou fallback.
