Criando vídeos curtos com wan2.7-video/text-to-video@pro: fluxo de trabalho de ponta a ponta da API hiapi

O sucesso de um vídeo curto depende da velocidade de iteração: você precisa de muitos clipes candidatos, formato vertical, com áudio e rápido. Este guia gira exatamente em torno disso, usando wan2.7-video/text-to-video@pro no hiapi — o modelo de texto para vídeo Tongyi Wanxiang 2.7 da Alibaba, com saída máxima de 1080P, áudio nativo e clipes de até 15 segundos. Cada estrutura de requisição, limite de parâmetro e mensagem de erro abaixo foi validada executando de fato contra a API em produção no momento da escrita deste artigo, e os dois clipes de demonstração incorporados também foram gerados exatamente pelo código mostrado.

O que o modelo oferece

wan2.7-video/text-to-video@pro é servido pelo endpoint unificado de tarefas assíncronas do hiapi (/v1/tasks). Características principais, verificadas contra o schema em produção:

• Saída: MP4 H.264, até 1080P, com faixa de áudio AAC nativa — o modelo gera som ambiente e efeitos sonoros a partir do seu prompt, sem necessidade de uma etapa de áudio separada.
• Duração: 2–15 segundos por clipe (segundos inteiros).
• Proporção: 16:9, 9:16, 1:1, 4:3, 3:4 — vertical real 9:16, compatível com formatos Shorts/Reels/TikTok, sem cortes.
• Cobrança: por segundo de vídeo de saída, a partir de US$ 0,167/segundo no momento da escrita — um clipe de 5 segundos em 1080P custa cerca de US$ 0,84. Antes de gerar em lote, confirme na página de preços.

O vídeo não tem modo síncrono: você precisa criar a tarefa, consultar até concluir e então baixar o resultado.

Exemplo mínimo funcional (curl)

Criar a tarefa:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video/text-to-video@pro",
    "input": {
      "prompt": "Filmagem macro em estúdio: uma gota de tinta azul safira cai em água limpa, florescendo em câmera lenta, os fios de tinta se estendem em forma de nuvem, fundo branco infinito e claro, iluminação high-key nítida, zumbido ambiente suave",
      "ratio": "16:9",
      "resolution": "1080P",
      "duration": 4
    }
  }'

Resposta:

{"code": 200, "data": {"taskId": "tk-hiapi-01KWGGS29FDZ8NRJW49YRQZ65R"}, "message": "success"}

Consultar o resultado:

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWGGS29FDZ8NRJW49YRQZ65R" \
  -H "Authorization: Bearer sk-YOUR_KEY"

Durante a renderização, data.status é handling; ao concluir, passa para success, e data.output[0].url contém o MP4. Essa requisição gerou exatamente este clipe:

⚠️ A URL de saída é um link temporário com timestamp expireAt. Após a tarefa ser concluída com sucesso, baixe o arquivo imediatamente para o seu próprio armazenamento — não faça hotlink nem armazene a URL no banco de dados.

Schema de entrada completo (validado contra a API em produção)

A API valida input estritamente e rejeita campos desconhecidos. A seguir está a lista completa de campos aceitos — obtida sondando diretamente o endpoint, não copiada de nenhum lugar:

Campo	Tipo	Restrição	Obrigatório
prompt	string	Descrição da cena; também orienta o áudio gerado	✅
ratio	string	Um entre 16:9, 9:16, 1:1, 4:3, 3:4	Opcional
resolution	string	720P ou 1080P	Opcional
duration	integer	2–15 (segundos)	Opcional
negative_prompt	string	Conteúdo a suprimir (ex.: marca d'água, sobreposição de texto)	Opcional
seed	integer	Reprodutível entre tentativas	Opcional
watermark	boolean	Ativa/desativa a marca d'água do provedor	Opcional

Duas armadilhas que ajudam a evitar erros 400:

• O nome do campo é ratio, não aspect_ratio — os modelos de imagem no hiapi usam aspect_ratio, mas este modelo de vídeo não. Enviar aspect_ratio retorna additional properties 'aspect_ratio' not allowed.
• duration é validado no servidor: duration: minimum: got 1, want 2 e maximum: got 999, want 15 são os erros exatos obtidos ao sair do intervalo 2–15.

Python de ponta a ponta: entra prompt, sai MP4 pronto para publicar

Este é o fluxo completo — criar, consultar, baixar — sem SDK, apenas com requests:

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}

def make_short(prompt: str, out_path: str, duration: int = 5,
               ratio: str = "9:16", seed: int | None = None) -> str:
    payload = {
        "model": "wan2.7-video/text-to-video@pro",
        "input": {
            "prompt": prompt,
            "ratio": ratio,               # 9:16 = vídeo curto vertical
            "resolution": "1080P",
            "duration": duration,          # 2..15 segundos
            "negative_prompt": "sobreposição de texto, marca d'água, mãos distorcidas",
        },
    }
    if seed is not None:
        payload["input"]["seed"] = seed

    task_id = requests.post(API, headers=HEADERS, json=payload).json()["data"]["taskId"]

    while True:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
        if task["status"] == "success":
            break
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(10)

    video_url = task["output"][0]["url"]   # link temporário — baixe imediatamente
    with open(out_path, "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
    return out_path

make_short(
    "Filmagem vertical em mão na feira noturna à hora dourada: um vendedor de comida de rua "
    "salteia macarrão chiando em um wok com chamas ondulando, vapor e faíscas laranja girando "
    "em direção à câmera, letreiros de neon exalam rosa e ciano suaves no fundo desfocado, "
    "profundidade de campo rasa, sensação documental dinâmica em mão, com sons de chiado e estalos",
    "night-market.mp4",
    duration=5,
    seed=20260702,
)

A seguir está o clipe realmente gerado por essa chamada — vertical 1080×1920, 5 segundos, com o chiado gerado a partir do texto do prompt:

Na minha execução, um clipe de 4 segundos em 16:9 levou cerca de 3 minutos para concluir, e um de 5 segundos em 9:16 um pouco mais — reserve alguns minutos por clipe, consulte a cada ~10 segundos e não sobrecarregue o endpoint.

Dicas de prompt para vídeos curtos: movimento e áudio são determinados pelo prompt

O schema não tem parâmetros de controle de câmera ou movimento — tudo sobre movimento, ritmo e som é orientado pela linguagem do prompt. O que funcionou nos meus testes:

• Nomeie explicitamente o comportamento da câmera: como "handheld" (em mão), "slow push-in" (aproximação lenta), "macro" (macro), "shallow depth of field" (profundidade de campo rasa). O tremor documental do clipe da feira noturna veio inteiramente da palavra "handheld".
• Descreva o áudio que deseja: o modelo gera som a partir do prompt. "sizzling and crackling sounds" (sons de chiado e estalos) e "gentle ambient hum" (zumbido ambiente suave) apareceram na faixa de áudio de saída.
• Coloque o gancho no início: para vídeos curtos, o primeiro segundo decide tudo. Coloque o elemento mais dinâmico (chamas no wok, gota de tinta caindo na água) no começo da descrição do prompt.
• Use negative_prompt de forma defensiva: "text overlay, watermark, distorted hands" (sobreposição de texto, marca d'água, mãos distorcidas) limpa as falhas mais comuns sem afetar o prompt principal.
• Fixe o seed ao iterar: com o seed fixo, altere uma frase do prompt por vez e observe o efeito real dessa frase.

Precisa de controle do primeiro frame? Use a variante de imagem para vídeo

Se o seu fluxo começa com um keyframe desenhado — imagem de produto, primeiro frame com a identidade da marca — o texto para vídeo não aceita entrada de imagem. O modelo complementar wan2.7-video/image-to-video@pro aceita: ele recebe um array media composto por objetos {"url": "...", "type": "image"}, combinado com os mesmos campos prompt / resolution / duration, animando o frame que você forneceu em vez de gerar um do zero. É o mesmo fluxo baseado em tarefas e a mesma cobrança por segundo. Um pipeline prático: gere o frame estático com o modelo de imagem, faça a revisão e depois anime apenas os frames aprovados — assim você só gasta com geração de vídeo nos frames já validados.

Erros comuns e o que realmente significam

• invalid input: prompt: missing required field "prompt" — prompt é o único campo obrigatório.
• invalid input: ratio: value must be one of '16:9', '9:16', '1:1', '4:3', '3:4' — você passou uma proporção não suportada pelo modelo (ou digitou errado).
• invalid input: <root>: additional properties '...' not allowed — campo desconhecido; o schema é estrito, verifique a tabela acima.
• status: "fail" com TASK_FAILED — a tarefa falhou após ser criada; crie uma nova tarefa (reutilize seu seed para manter a reprodutibilidade).
• O arquivo baixado é pequeno ou não reproduz — provavelmente você acessou uma URL de saída expirada. Verifique novamente o expireAt e baixe imediatamente após o success.

Resumo

Um POST, um loop de consulta, um download — essa é toda a distância entre um prompt de texto e um MP4 vertical com áudio pronto para publicar. Se você vai construir um pipeline de vídeos curtos, obtenha uma API key no console, comece com a função Python acima e explore o restante do catálogo de modelos — o mesmo padrão /v1/tasks (como mostrado no nosso guia do seedance-2.0-fast) se aplica a todos os modelos de vídeo da plataforma, então trocar de modelo depois exige apenas uma linha.