Início Rápido da API Hunyuan Video Fast

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 preparação 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 o URL do vídeo quando a tarefa é concluída. Este guia cobre 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 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
• Preparação e revisão interna — obter resultados compartilháveis rapidamente e, em seguida, usar 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 restritos

Se a qualidade da saída for a principal restrição — transmissão, entrega final ou movimento fotorrealista — use o endpoint padrão do Hunyuan Video em vez disso.

Etapa 1: Obtenha sua Chave de API da Novita AI

Registre-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 em arquivos fonte.

export NOVITA_API_KEY="sua_chave_api_aqui"

Etapa 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

Etapa 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 na próxima etapa.

Etapa 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 — ele 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"Tarefa falhou: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Tarefa {task_id} não foi concluída 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

# Etapa 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 do horizonte de uma cidade 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 "ID da Tarefa: $TASK_ID"

# Etapa 2: Consulte 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 "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 do vídeo, assunto, movimento e estilo
negative_prompt	string	Não	Elementos a evitar na saída (ex.: “borrado, baixa qualidade”)
width	inteiro	Não	Largura da saída em pixels — consulte a documentação da API para valores suportados
height	inteiro	Não	Altura da saída em pixels — combinado com width para definir a resolução
seed	inteiro	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 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 é geralmente por clipe gerado e varia conforme a resolução e duração. Consulte a página de preços antes de construir um modelo de custo para cargas de trabalho de produção.

Confirme os seguintes limites na documentação oficial antes de implantar:

• Comprimento 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 limites de tarefas simultâneas 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 expirada. Confirme que NOVITA_API_KEY está definida e 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 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 andamento. 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 — O URL expirou (video_url_ttl decorrido). Em produção, baixe ou transfira o vídeo imediatamente após TASK_STATUS_SUCCEED — não dependa do URL hospedado como armazenamento permanente.

Problemas consistentes de qualidade em tipos específicos de prompt — Mude para uma abordagem de refinamento do prompt: descreva o assunto, a ação, o ângulo da câmera e o 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, então 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 — 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 fina ao prompt são menores que o modelo padrão. Use a variante rápida para iteração de prompts, tarefas em lote de alto rendimento ou preparação; 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 reproduzo uma saída de vídeo específica?

Defina seed para 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. O preço por clipe para modelos de vídeo pode mudar; sempre consulte 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 o tratamento adequado. Projete seu pipeline em torno do envio de tarefas assíncronas, 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 lide com TASK_STATUS_FAILED com uma estratégia de repetição ou fallback.

Artigos Recomendados

• Hunyuan Video: Um Modelo de Texto para Vídeo com IA de Código Aberto
• API Hunyuan Image 3 na Novita AI: Guia de Geração de Texto para Imagem
• Início Rápido da API Kling V3.0 4K