Como usar seedance-2.0-fast via API hiapi: curl, Python e requisições executáveis

Este guia mostra a requisição mínima para gerar vídeo com seedance-2.0-fast, todos os campos de entrada que o modelo realmente aceita e como aguardar o resultado por polling ou callback. Cada estrutura de requisição e mensagem de erro abaixo foi verificada em execução na API real, então você pode copiar o código diretamente.

O que você vai construir e o que precisa preparar

O objetivo é um só: enviar um prompt de texto e receber de volta uma URL de MP4 para download. seedance-2.0-fast é a versão otimizada para velocidade do Seedance 2.0 — ela troca a resolução máxima (limitada a 720p) por geração mais rápida, o que a torna ideal para prévias, ciclos de iteração e grandes lotes de clipes curtos.

Você só precisa de uma coisa: uma chave de API da hiapi. Obtenha-a no seu dashboard; o formato é algo como sk-.... Todos os modelos de vídeo (incluindo este) são servidos pelo endpoint unificado de tarefas assíncronas: você primeiro POST /v1/tasks para criar a tarefa e depois busca o resultado pelo id da tarefa. Vídeo não tem modo síncrono.

O preço atual por clipe está na página de preços (o modelo acabou de ser lançado, então confie nela e não em qualquer número de posts de blog).

Exemplo mínimo executável (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": "seedance-2.0-fast",
    "input": {
      "prompt": "A paper boat drifts down a rain-soaked street at dusk, cinematic, slow dolly-in",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

O id da tarefa na resposta fica em data.taskId:

{
  "data": {
    "taskId": "task_abc123..."
  }
}

Faça polling dessa tarefa até o status atingir o estado terminal:

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

Quando data.status for "success", a URL do vídeo fica em data.output[0].url. Essa URL é assinada e expira — baixe o arquivo imediatamente, não faça hotlink:

curl -o clip.mp4 "<the output url>"

Todos os campos de entrada (verificados)

Somente prompt é obrigatório. Qualquer campo que não esteja nesta tabela será rejeitado com 400 — o schema não permite propriedades adicionais.

Campo	Tipo	Obrigatório	Valores aceitos
prompt	string	Sim	Comprimento mínimo de 3 caracteres
duration	inteiro	Não	4–15 (segundos)
resolution	string	Não	480p, 720p
aspect_ratio	string	Não	1:1, 4:3, 3:4, 16:9, 9:16, 21:9, adaptive

Dois pontos merecem destaque especial:

• duration é inteiro, não string. Enviar "duration": "5" falha na validação com o erro duration: got string, want integer.
• Não há entrada de imagem. seedance-2.0-fast só suporta texto para vídeo; campos como image_urls são rejeitados pelo schema. Se você precisa de imagem para vídeo, consulte o guia de fluxo de trabalho da API de imagem para vídeo para saber quais modelos suportam esse recurso.

O mesmo fluxo em Python

Sem SDK — requests já basta:

import time
import requests

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

def create_task(prompt: str, duration: int = 5,
                resolution: str = "720p", aspect_ratio: str = "16:9") -> str:
    payload = {
        "model": "seedance-2.0-fast",
        "input": {
            "prompt": prompt,
            "duration": duration,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    r = requests.post(API_BASE, json=payload, headers=HEADERS, timeout=60)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

task_id = create_task(
    "A barista pours latte art in a sunlit cafe, shallow depth of field"
)
task = wait_task(task_id)
video_url = task["output"][0]["url"]

# The URL is signed and expires — persist the bytes immediately.
with open("clip.mp4", "wb") as f:
    f.write(requests.get(video_url, timeout=120).content)
print("saved clip.mp4")

Trate qualquer status diferente de success / fail como "ainda em execução" — assim o loop continua robusto mesmo que os nomes dos estados intermediários mudem no futuro.

Considerações para produção

Use callback em vez de polling

Para qualquer cenário além de scripts, registre um callback ao criar a tarefa e pule o polling por completo:

{
  "model": "seedance-2.0-fast",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your-app.com/hooks/hiapi", "when": "final" }
}

Com "when": "final", quando a tarefa atingir o estado terminal, seu endpoint receberá exatamente um POST. O polling serve para CLI e notebooks; quando você roda em grande escala, os callbacks são superiores (sem requisições desperdiçadas e sem latência do intervalo de polling). Se seu hook parece não disparar, consulte o guia de solução de problemas de callback — quase sempre é um problema de acessibilidade da URL ou seu handler retornando uma resposta não-2xx.

Idempotência

Criar tarefas não é gratuito, então evite envios duplicados do seu lado: faça cada evento de negócio corresponder a no máximo uma chamada POST /v1/tasks (por exemplo, armazene o taskId associado à sua linha de pedido/tarefa antes de tentar novamente). Se seu processo cair após criar a tarefa, você pode recuperar relendo o taskId armazenado e retomando GET /v1/tasks/<id> — a tarefa continua rodando no servidor, independentemente de você fazer polling ou não.

Erros que você realmente vai encontrar

Sintoma	Significado	Correção
400 com error_code: "INVALID_REQUEST"	A entrada não passou na validação do schema; message indica o campo específico, por exemplo duration: maximum: got 20, want 15	Corrija o campo; somente os quatro campos da tabela acima são permitidos
401 com error.code: "permission_denied"	Chave inválida, ou válida mas não habilitada para este modelo	Verifique a chave no dashboard; as permissões de modelo são definidas por chave
404 no GET com "task not found"	Id de tarefa incorreto ou que não pertence a essa conta	Use o taskId retornado na criação, e da mesma conta
Status da tarefa "fail" com um objeto error	A geração em si falhou	Leia error.code/error.message; ajuste o prompt e tente novamente

Observe os dois formatos de erro: erros de validação colocam message no nível superior, enquanto erros de autenticação ficam aninhados em error. Se você escrever um middleware genérico, precisa tratar os dois casos.

Quando usar seedance-2.0-fast

Se você precisa de saída em 1080p ou 4K, use o seedance-2.0 completo — mesmo endpoint, mesmo fluxo, limite de resolução maior (e ele exige especificar aspect_ratio explicitamente). Para uma visão mais abrangente de como a linha Seedance se compara a outros modelos de vídeo da plataforma, consulte a comparação de modelos de vídeo. A referência completa de parâmetros de cada modelo está na documentação, e a página do modelo acompanha os recursos e o status de preços atuais.

Perguntas frequentes

Quais resoluções o seedance-2.0-fast suporta? 480p e 720p. Esse é o preço da velocidade — o seedance-2.0 completo, no mesmo fluxo /v1/tasks, chega a 1080p e 4k.

Posso fazer imagem para vídeo com seedance-2.0-fast? Não. O schema de entrada aceita apenas prompt, duration, resolution e aspect_ratio; campos de imagem são rejeitados com erro de validação. Para opções de imagem para vídeo na hiapi, consulte o guia de fluxo de trabalho de imagem para vídeo.

Qual é a duração máxima do vídeo gerado? duration aceita um inteiro de 4 a 15 segundos. Valores fora desse intervalo falham na validação antes da criação da tarefa (requisições rejeitadas não são cobradas).

Devo usar polling ou callback? Para scripts e baixa concorrência, polling a cada ~5 segundos é suficiente. Em escala de produção, passe callback: {"url": ..., "when": "final"} na criação e deixe a hiapi enviar o estado terminal para você — uma requisição em vez de dezenas.

Por que uma chave que funciona para outros modelos recebe 401 permission_denied aqui? O acesso a modelos é delimitado por chave. Um 401 com permission_denied neste modelo significa que a chave existe mas não está habilitada para seedance-2.0-fast — verifique as permissões de modelo dessa chave no dashboard.

Quanto tempo dura a URL de saída? É uma URL assinada e expira. Baixe o MP4 imediatamente após o sucesso da tarefa e armazene-o por conta própria; não incorpore a URL de saída bruta em nenhum lugar duradouro.