Tutorial
Como usar pixverse-v6-max/text-to-video pela API HiAPI: exemplos executáveis em curl e Python
Nesta página
O que este endpoint faz e quando usá-lo
pixverse-v6-max/text-to-video é o endpoint de texto para vídeo na HiAPI. Você envia um prompt de texto descrevendo a cena desejada e o endpoint retorna o vídeo renderizado. Como a geração de vídeo leva tempo, este endpoint é assíncrono: a requisição inicial não retorna o vídeo diretamente, mas sim um identificador de tarefa que você usa para consultar o progresso e obter o resultado final.
Esse formato de "requisição — confirmação — polling" é o modelo mental central de todo este tutorial. O fluxo interno é sempre o mesmo:
- Envie a tarefa de geração com o prompt e os parâmetros.
- Receba imediatamente um identificador de tarefa.
- Consulte a tarefa repetidamente até que ela reporte conclusão (ou falha).
- Baixe ou incorpore a URL do vídeo resultante.
Quando este endpoint é adequado
Escolha pixverse-v6-max/text-to-video quando você tiver apenas uma descrição e nenhum material de origem — por exemplo, criar um teaser de produto a partir de um briefing em texto, gerar um clipe de fundo para um app ou produzir uma prévia de storyboard. Se você já tem uma imagem e quer animá-la, isso é um fluxo de imagem para vídeo, não este endpoint. Se você quer iterar prompts conversacionalmente com o modelo, isso é outro modo de interação. Este endpoint é o caminho direto e de geração única de texto para vídeo.
Como a geração é assíncrona, ele também se adequa a arquiteturas baseadas em fila: um backend web recebe a requisição do usuário, envia a tarefa, e um worker faz o polling e entrega o resultado depois. Nenhuma etapa da chamada bloqueia até a renderização completa.
Antes de começar: autenticação e fundamentos da requisição
Antes de escrever qualquer código, confirme três coisas.
1. Uma chave de API
Toda requisição à HiAPI precisa ser autenticada com uma chave de API. Trate-a como uma senha: não a envie para repositórios de código, carregue-a de variáveis de ambiente e rotacione-a imediatamente em caso de vazamento. Os exemplos abaixo a leem de HIAPI_API_KEY, então exporte-a no shell primeiro:
export HIAPI_API_KEY="your_key_here"
2. A URL base correta
Todas as requisições vão para a URL base da API HiAPI, com o caminho do endpoint anexado. Use a base URL registrada na sua conta HiAPI em vez de codificar um hostname fixo a partir de posts de blog — se estiver em dúvida, consulte a referência da API no painel. Os exemplos abaixo usam $HIAPI_BASE_URL como marcador para esse valor.
3. Convenções JSON
O envio e a consulta de status são JSON sobre HTTPS:
- Envie
Content-Type: application/jsonem toda requisição com corpo. - Envie
Authorization: Bearer $HIAPI_API_KEYem toda requisição (incluindo consultas de status). - Espere JSON de volta, inclusive em erros — leia o corpo da resposta de erro, não apenas o código de status HTTP.
Verificação rápida de sanidade
Se você tiver um endpoint leve disponível (como as rotas de models ou account), chame-o uma vez antes de tocar no endpoint de vídeo. Um 200 ali prova que sua chave, base URL e formato de cabeçalhos estão corretos, eliminando três variáveis da depuração posterior.
Uma requisição curl executável
A seguir está a chamada de envio completa. O caminho do endpoint é pixverse-v6-max/text-to-video; o corpo carrega seu prompt e parâmetros de geração.
curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Noite, um beco de neon encharcado pela chuva, movimento lento de dolly para frente, estética cinematográfica",
"duration": 5,
"aspect_ratio": "16:9"
}'
Explicação campo a campo
prompt— a descrição textual. Seja explícito sobre sujeito, movimento, movimento de câmera e atmosfera. Esta é a alavanca mais importante para a qualidade da saída.duration— a duração solicitada do clipe. Veja a seção de duração e proporção abaixo.aspect_ratio— a proporção da imagem de saída, por exemplo16:9,9:16,1:1.
O que é retornado
Um envio bem-sucedido retorna um objeto JSON contendo um identificador de tarefa — o handle usado para o polling. Consulte a referência da API para o nome exato do campo; neste tutorial o chamamos de task_id. Guarde-o:
TASK_ID=$(curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"Noite, um beco de neon encharcado pela chuva, movimento lento de dolly para frente, estética cinematográfica","duration":5,"aspect_ratio":"16:9"}' \
| python -c 'import sys,json; print(json.load(sys.stdin)["task_id"])')
echo "$TASK_ID"
Observe o que a resposta não contém: o vídeo. A geração roda em segundo plano. Trate a resposta de envio como um recibo, não como o resultado.
A mesma requisição em Python
A versão em Python corresponde exatamente à chamada curl. Usamos requests por brevidade, mas httpx ou urllib funcionam igualmente — o único requisito são os mesmos cabeçalhos e o mesmo corpo JSON.
import os
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 = {
"prompt": "Noite, um beco de neon encharcado pela chuva, movimento lento de dolly para frente, estética cinematográfica",
"duration": 5,
"aspect_ratio": "16:9",
}
resp = requests.post(
f"{BASE_URL}/pixverse-v6-max/text-to-video",
headers=headers,
json=payload,
timeout=30,
)
if resp.status_code >= 400:
# Imprima o corpo da resposta de erro do servidor — ele costuma indicar o campo problemático
raise RuntimeError(f"submit failed {resp.status_code}: {resp.text}")
data = resp.json()
task_id = data["task_id"]
print("submitted:", task_id)
Pontos que vale a pena copiar
json=payloadserializa automaticamente o corpo e define o tipo de conteúdo. Se você usardata=json.dumps(payload), mantenha o cabeçalhoContent-Typeexplícito.- Definir um timeout do cliente no envio evita conexões travadas. Ele não limita o tempo de geração — a geração ocorre no servidor, e é exatamente por isso que é preciso fazer polling.
- Verifique o código de status antes de analisar. O corpo de uma resposta 4xx costuma ser mais informativo que o código em si; imprima-o.
- Nunca registre a chave de API. Registre o
task_id— ele é seguro de armazenar e é o seu handle de depuração.
Parâmetros de duração e proporção
Esses dois campos são a fonte mais comum de rejeição de requisições, então merecem atenção.
duration
duration define o comprimento do clipe solicitado, em segundos. Os valores que podem ser solicitados são limitados pela faixa suportada pelo endpoint; enviar um valor fora dessa faixa geralmente produz um erro de validação de parâmetro, e não um clipe truncado silenciosamente. Escolha entre os valores suportados documentados na referência da API e mantenha-o como inteiro. Clipes mais longos levam mais tempo para renderizar, então durante o desenvolvimento prefira a duração mais curta suportada — você está validando o fluxo, não a direção de fotografia.
aspect_ratio
aspect_ratio é uma string no formato W:H. Faça-a corresponder ao local onde o vídeo será exibido:
16:9— paisagem: hero de sites, players estilo YouTube, fundos de desktop.9:16— retrato: feeds de vídeos curtos e stories em dispositivos móveis.1:1— quadrado: layouts de grade e miniaturas.
Escolher a forma errada aqui é barato de corrigir, mas caro de descobrir tarde demais: uma nova renderização consome outro ciclo completo de geração, então determine o cenário de exibição alvo antes de enviar.
O que verificar quando rejeitado
- Incompatibilidade de tipo —
durationenviado como string ("5") em vez de número, ouaspect_ratioenviado como dois números. Mantenha duration numérico e aspect ratio como string. - Valores não suportados — duração ou proporção fora da faixa documentada. Confira cada um contra a lista de referência.
- Nomes de campos — erros de digitação como
aspectRatiooudurationSeconds, na melhor das hipóteses, são tratados silenciosamente como campos desconhecidos. Copie os nomes de campos da documentação de referência.
Método para localizar rapidamente o campo problemático: reenvie apenas com prompt, depois adicione os parâmetros um a um. A primeira rejeição indicará o campo problemático.
Fazer polling da tarefa assíncrona até o vídeo ficar pronto
O polling é um laço que segue três regras: verificar status, dormir, parar no estado terminal. Adicione também um limite máximo para evitar que tarefas travadas girem indefinidamente.
import time
import requests
def wait_for_video(task_id, base_url, api_key, timeout=600):
headers = {"Authorization": f"Bearer {api_key}"}
url = f"{base_url}/tasks/{task_id}" # Consulte a referência da API para a rota de status
deadline = time.time() + timeout
delay = 2
while time.time() < deadline:
r = requests.get(url, headers=headers, timeout=30)
r.raise_for_status()
task = r.json()
status = task["status"]
if status == "succeeded":
return task["result"]["video_url"]
if status == "failed":
raise RuntimeError(f"generation failed: {task.get('error')}")
time.sleep(delay)
delay = min(delay * 1.5, 15) # Backoff suave, com limite máximo
raise TimeoutError(f"task {task_id} not finished in {timeout}s")
Por que o backoff importa
Fazer polling a cada segundo em uma geração que leva um minuto desperdiça dezenas de requisições. Comece com um intervalo curto e aumente gradualmente — o multiplicador com teto acima se estabiliza em um intervalo confortável, sem martelar a API com frequência. Se você for rodar muitas tarefas, uma fila com um único worker de polling é mais amigável do que um laço por requisição.
Tratamento do resultado
Depois que a tarefa é concluída com sucesso, a resposta traz a URL do vídeo. Busque-a prontamente e, se o resultado precisar ser retido, copie-o para seu próprio armazenamento — URLs assinadas não são permanentes. Antes de entregar o arquivo ao usuário, verifique o tipo de conteúdo e o tamanho no download, e registre o task_id junto ao ativo armazenado, para que qualquer problema futuro possa ser rastreado até o registro exato de geração.
Diagnóstico de erros comuns
Em caso de falha, percorra esta lista. A maioria das falhas se enquadra em uma destas quatro categorias.
Autenticação e acesso
- 401 / unauthorized — chave ausente, malformada ou não enviada. Confirme que o cabeçalho é exatamente
Authorization: Bearer <key>e que a variável de ambiente está realmente definida no shell ou processo que faz a chamada. - 403 / forbidden — a chave é válida, mas não tem permissão para este endpoint. Verifique o escopo de permissões da chave no painel.
Validação da requisição
- 400 / 422 — JSON malformado ou valor de campo inválido. Imprima o corpo completo da resposta de erro; ele geralmente indica o campo. Verifique novamente o tipo de
duratione o formato string deaspect_ratio. - 404 no envio — caminho do endpoint errado. Confirme que o caminho é exatamente
pixverse-v6-max/text-to-videoe que sua base URL não tem segmentos de caminho duplicados ou ausentes.
Falhas no nível da tarefa
- Status
failed— a tarefa foi aceita mas a geração falhou. Leia a mensagem de erro na tarefa; ela distingue rejeição de conteúdo de falha interna. Um prompt rejeitado é problema do prompt, não da API — ajuste e reenvie. - Preso no estado de execução — defina um prazo para o polling e trate o timeout como uma falha a ser tratada, não como uma exceção que derruba o serviço.
Problemas operacionais
- 429 / rate limit atingido — muitos envios ou polls em andamento. Reduza a concorrência e respeite qualquer dica de retry na resposta.
- Timeout de conexão no envio — problema de rede ou proxy, não de geração. Reenvie com backoff, mas apenas se você puder tolerar possíveis tarefas duplicadas.
- 404 na URL do vídeo durante o download — a URL expirou. Busque novamente o resultado da tarefa em vez de reutilizar a URL antiga.
Um hábito repetível
A cada falha, registre três valores: o código de status HTTP, o corpo da resposta e (se houver) o task_id. Esses três transformam "quebrou" em "quebrou aqui", e essa é a única chave para depurar mais rápido.
O que fazer a seguir
Você agora tem o ciclo completo: autenticar, enviar, obter o identificador da tarefa, fazer polling com backoff e obter o resultado. Para produção, encapsule envio e polling em uma pequena classe de cliente, armazene o task_id e o prompt junto a cada ativo para rastreabilidade, e mova o polling para um worker em segundo plano, para que as requisições voltadas ao usuário nunca bloqueiem por causa da renderização.
Em seguida, explore endpoints adjacentes na documentação de referência da HiAPI — imagem para vídeo para animar quadros estáticos existentes, e o modo de interação iterativa de prompts para refinar o estilo visual antes de comprometer uma geração completa. A forma da requisição que você aprendeu aqui se transfere quase sem alterações.
Artigos relacionados
Ver todos os artigos →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio