Blogue

Tutorial

Como chamar wan2.7-video de texto para vídeo pela API HiAPI: curl e Python

Nov 12, 2026
Imagem de capa do blog HiAPI: sobre um fundo azul-petróleo profundo, formas geométricas de seções minerais compostas por planos facetados, em tons de verde-azulado e malaquita, com acabamento fosco.
Nesta página

O que você vai construir neste tutorial

Ao final deste guia, você terá um pequeno pipeline funcional: enviar uma tarefa de texto para vídeo para wan2.7-video/text-to-video pela API HiAPI — primeiro uma vez com curl, depois uma vez com Python — e então aguardar a conclusão da geração do vídeo.

As duas chamadas são deliberadamente equivalentes. A versão em curl é a implementação de referência, que você pode colar no terminal para confirmar se as credenciais e o corpo da requisição estão corretos. A versão em Python encapsula a mesma requisição em uma função, fácil de colocar em um script ou serviço, e inclui polling, tratamento de erros e padrões razoáveis.

Como a geração de vídeo é muito mais lenta do que o preenchimento de chat, todo o fluxo é assíncrono: envie a tarefa, obtenha um identificador e faça polling até que a tarefa reporte um estado terminal. O restante do texto gira em torno desse ciclo de vida, portanto, se você depois mudar para imagem para vídeo ou outro modelo de vídeo da mesma família de endpoints, a estrutura geral continua válida.

Antes de enviar a primeira requisição

Para que a primeira chamada seja bem-sucedida, é preciso atender a três condições.

Credenciais

Você precisa de uma chave de API da HiAPI, enviada como bearer token por meio do cabeçalho Authorization. Mantenha-a em uma variável de ambiente, em vez de escrevê-la no código-fonte:

export HIAPI_API_KEY="your-key-here"

O identificador de modelo conhecido

O identificador de modelo é uma string exata. Neste tutorial, o valor é wan2.7-video/text-to-video — incluindo o sufixo de tarefa. Grafias aproximadas como wan2.7-video ou wan2.7/text-to-video serão rejeitadas, então copie o identificador da lista de modelos, não o escreva de memória.

Um prompt que possa ser avaliado

Iterar geração de vídeo às cegas custa caro. Escreva antes um prompt específico (sujeito, ação, comportamento de câmera, iluminação, estilo), para que, quando o resultado voltar, você possa julgar se o que precisa ser ajustado são essas configurações, e não a formulação.

Você também precisará de um cliente HTTP e de uma forma de ler JSON. No lado do shell, use curl com jq; no lado do script, use Python com requests.

Anatomia do corpo da requisição

Uma requisição de texto para vídeo é um objeto JSON cujos campos podem ser agrupados em três categorias.

Identidade

  • model — o identificador exato do modelo, ou seja, wan2.7-video/text-to-video.

Conteúdo

  • prompt — o texto que descreve o vídeo desejado. É o campo que mais influencia; especifique movimento, composição e estilo, em vez de empilhar adjetivos.
  • negative_prompt — opcional. Descreve o que não deve aparecer. Útil para suprimir artefatos comuns, mas não substitui um bom prompt.

Configurações de geração

  • duration — a duração do clipe de saída.
  • resolution — o tamanho/nível de resolução da saída.
  • seed — opcional. Fixe-o quando quiser comparar dois prompts ou duas alterações de configuração a partir de um ponto de partida estável.

O corpo mínimo da requisição precisa apenas de model e prompt; a plataforma aplica valores padrão aos demais campos. Mas valores padrão não são as escolhas que você fez — consulte a seção sobre duração e resolução abaixo para entender por que convém defini-los explicitamente em produção.

Mantenha o corpo da requisição plano e raso. Aninhar apenas os campos que realmente pertencem a um subobjeto torna a requisição mais legível e os erros de schema mais fáceis de encontrar.

Enviar a tarefa com curl

Abaixo está um exemplo completo de envio. O endpoint recebe JSON e retorna um identificador de tarefa, não o vídeo em si.

curl -X POST "$HIAPI_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video/text-to-video",
    "prompt": "Plano de acompanhamento em travelling lento por um beco de neon molhado pela chuva à noite, poças refletivas no chão, profundidade de campo rasa, color grading cinematográfico",
    "duration": 5,
    "resolution": "720p"
  }'

Um envio bem-sucedido retorna um objeto que contém o identificador da tarefa ou do job e o status. A estrutura é aproximadamente assim:

{
  "id": "job_abc123",
  "status": "queued",
  "model": "wan2.7-video/text-to-video"
}

Há dois pontos a observar. Primeiro, status não é succeeded — nesse momento nada foi renderizado. Segundo, não há URL de vídeo na resposta. Essa URL só aparece depois que a tarefa atinge um estado terminal.

Se você quiser manter o identificador na sessão do shell para a etapa de polling:

JOB_ID=$(curl -s -X POST "$HIAPI_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | jq -r '.id')
echo "$JOB_ID"

Mover o corpo da requisição para payload.json mantém o comando curto e facilita ajustar o prompt entre execuções.

Enviar a tarefa com Python

A versão em Python é a mesma requisição, apenas mais confortável de usar. O que no curl é cabeçalho ou chave JSON aqui vira argumento nomeado.

import os
import time
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "wan2.7-video/text-to-video",
    "prompt": (
        "Plano de acompanhamento em travelling lento por um beco de neon molhado pela chuva à noite, "
        "poças refletivas no chão, profundidade de campo rasa, color grading cinematográfico"
    ),
    "duration": 5,
    "resolution": "720p",
}

resp = requests.post(
    f"{BASE_URL}/v1/video/generations",
    headers=HEADERS,
    json=payload,
    timeout=30,
)
resp.raise_for_status()
job = resp.json()
print(job["id"], job["status"])

A correspondência com a versão em shell é um para um:

  • -H "Authorization: ..." → o dicionário HEADERS.
  • -d '<json>' → json=payload. Passar um dicionário em vez de uma string significa que o requests cuida da serialização, então você não envia JSON malformado por engano.
  • O .id extraído com jq → job["id"].

Há dois hábitos específicos de Python que valem a pena cultivar desde já. Sempre defina um timeout na chamada de envio — a requisição é pequena e deve retornar rápido, então uma longa espera indica problema de conexão, não de renderização. E chame raise_for_status() antes de ler o corpo da resposta, para que uma falha na camada HTTP produza um traceback claro, em vez de um KeyError confuso em job["id"].

Lidar com tarefas assíncronas e polling

O polling é onde a maioria das integrações se torna robusta ou instável. As tarefas têm um ciclo de vida — normalmente enfileirada, em processamento e, depois, bem-sucedida ou falha (estado terminal) — e seu loop precisa lidar com os três casos.

def wait_for_job(job_id, interval=5, max_attempts=120):
    url = f"{BASE_URL}/v1/video/generations/{job_id}"
    for attempt in range(max_attempts):
        r = requests.get(url, headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "succeeded":
            return data
        if status in ("failed", "cancelled"):
            raise RuntimeError(f"Job {job_id} ended as {status}: {data.get('error')}")
        time.sleep(interval)
    raise TimeoutError(f"Job {job_id} still not finished after {max_attempts} polls")

Há algumas decisões de design nesse loop cuja importância é maior do que parece:

Verifique explicitamente os estados terminais. Tratar todo estado que não seja succeeded como "continue aguardando" faz com que tarefas com falha consumam silenciosamente todo o seu orçamento de polling. Combine com os estados de falha e lance uma exceção.

Escolha o intervalo de polling conscientemente. A renderização de vídeo leva de dezenas de segundos a vários minutos. Fazer polling a cada 200 ms só adiciona carga e não traz nenhuma informação nova. Comece com cerca de 5 segundos; se as tarefas costumam demorar muito, aumente o intervalo em vez de aumentar o número de tentativas.

Sempre limite o loop. Um limite de max_attempts transforma uma espera infinita em um TimeoutError diagnosticável. Registre também o ID da tarefa — é esse valor que você vai precisar ao investigar problemas.

Respeite os limites de taxa. Se enviar tarefas em lote, não dispare todas as requisições de polling ao mesmo tempo. Usar um poller compartilhado que roda em intervalos fixos, ou um limitador simples no cliente, mantém você dentro dos limites.

Em caso de sucesso, a resposta contém a localização do ativo concluído. Baixe-o imediatamente e não trate o registro da tarefa como armazenamento permanente.

Escolher duração e resolução

Essas duas configurações afetam a saída mais do que qualquer outro parâmetro, e ambas influenciam o tempo de execução da tarefa e o custo. O consumo cobrado é calculado em segundos de saída, e a resolução determina o trabalho por segundo — portanto, trate ambas como escolhas deliberadas para o caso de uso, não como campos que podem ficar nos padrões.

Duração

Clipes mais longos dão espaço para a ação se desenvolver, mas cada segundo extra significa mais renderização e custo maior, e gerações longas também são mais propensas a problemas de coerência. Recomendações práticas:

  • Curto (alguns segundos) — loops para redes sociais, visuais principais de produto, B-roll. Menor custo de iteração e mais fácil de avaliar.
  • Médio — batidas narrativas, planos de estabelecimento.
  • Longo — use apenas quando a história realmente exigir. Se precisar de um vídeo longo, considere gerar vários clipes curtos e editá-los juntos; isso costuma ser mais barato do que uma única renderização longa e lhe dá mais controle.

Ao iterar o prompt, gere o clipe mais curto que o modelo permitir. Avalie composição e movimento nesse comprimento e, quando estiver satisfeito, aumente a duração.

Resolução

Resolução mais alta significa mais pixels por quadro, mais tempo de renderização e custo maior. Mas em telas pequenas, sua importância é menor do que você imagina. Um master em 1080p serve para entregar ao cliente; um rascunho em 720p (ou menos) serve para julgar se o prompt funciona.

O padrão eficiente é um fluxo de trabalho em duas etapas: fixe o prompt e a duração em baixa resolução e depois execute novamente a tarefa final na resolução de entrega. Não itere na configuração mais alta — você gastará a maior parte do orçamento em material descartado.

Diagnosticar erros comuns

A maioria das falhas vem de como a requisição é organizada, não do modelo em si. Antes de tirar conclusões sobre a capacidade do modelo, investigue as categorias a seguir em ordem.

401 / 403 — problemas de credencial

Verifique se a chave está definida no ambiente realmente visível ao processo (uma chave exportada em um shell não é visível para um serviço systemd), se o cabeçalho é Authorization: Bearer <key> e se não há espaços em branco no final da variável. Ao depurar, imprima apenas os primeiros caracteres da chave, nunca a chave completa.

404 — caminho ou modelo errado

O caminho do endpoint e o identificador do modelo são coisas diferentes, e ambos precisam estar exatos. Confirme a URL para a qual você faz POST e confirme que wan2.7-video/text-to-video foi copiado caractere por caractere da lista de modelos. Uma chave válida com a string de modelo errada ainda retorna um erro do tipo not-found.

400 — corpo da requisição malformado

Esta é a categoria mais comum. Causas frequentes incluem: campos numéricos como duration enviados como string "5", o prompt enviado como lista em vez de string, ou o corpo da requisição acidentalmente codificado duas vezes. A triagem mais rápida é reenviar exatamente o mesmo comando curl — se a chamada pelo shell funciona e a do Python falha, o problema está em como o script monta o dicionário, não na requisição em si.

422 / erros de validação

A sintaxe é válida, mas a semântica tem problema: duração fora do intervalo suportado, nível de resolução desconhecido ou campo obrigatório ausente. Leia a mensagem de erro — normalmente ela indica o campo problemático.

Tarefa falha após o envio

A chamada de envio foi bem-sucedida, mas a renderização não. Pode ser uma recusa por política de conteúdo ou uma falha temporária de renderização. Registre o ID da tarefa e o payload de erro; se for um problema temporário, reenviar o mesmo payload é um primeiro passo razoável. Se o mesmo prompt falhar repetidamente, mude a formulação do prompt ou as configurações de geração, em vez de repetir a mesma requisição.

O polling nunca termina

Se a tarefa ficar em processamento muito mais tempo do que tarefas semelhantes, pare o polling, registre o ID da tarefa e trate-a como falha. Casos de cauda longa são raros o suficiente para que um timeout limitado com mensagem de erro clara seja melhor do que um loop aberto.

A cada novo problema, comece pela implementação de referência em curl: ela elimina seu código da equação e isola se o problema está na requisição ou no cliente.

Artigos relacionados

Ver todos os artigos →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API