Blogue

Tutorial

Como chamar seedance-2.5-flash de texto para vídeo pela API HiAPI (curl e Python)

Um passo a passo funcional para desenvolvedores: endpoint, parâmetros, tratamento assíncrono de tarefas e exemplos executáveis em curl e Python

Nov 19, 2026
Imagem de capa: setas largas aninhadas sobre fundo azul-índigo profundo avançam em etapas com bordas dianteiras em tom pêssego, formando uma composição geométrica semelhante a um fluxo de sinal.
Nesta página

O que seedance-2.5-flash/text-to-video oferece

seedance-2.5-flash/text-to-video é um endpoint de geração de vídeo a partir de texto na API HiAPI. Você envia um prompt de texto descrevendo a cena desejada e o modelo retorna o vídeo gerado. A convenção é simples assim: entra texto, sai vídeo.

Como a geração de vídeo leva mais tempo do que uma completion de chat típica, este endpoint é assíncrono. Uma única chamada não fica bloqueada esperando o vídeo ficar pronto; em vez disso, ela cria uma tarefa de geração, e você obtém o resultado quando a tarefa chega a um estado final. Se você já integrou qualquer API de mídia de longa duração, esse formato será familiar: enviar, guardar o identificador da tarefa e depois buscar o resultado.

Portanto, o trabalho de integração do seu lado se divide em três coisas: montar uma requisição de envio válida, persistir o ID da tarefa e obter de forma confiável o vídeo concluído. Este tutorial percorre esses três passos com código executável em curl e Python, e depois explica a validação de parâmetros, o trade-off entre polling e callback, e os modos de falha em que a maioria das primeiras integrações tropeça.

Se você está construindo um pipeline que converte prompts em clipes curtos de vídeo de forma programática — ferramenta de conteúdo, backend de protótipo ou serviço interno de geração — este guia é para você. Se você precisa de respostas síncronas, ou se procura geração de imagens em vez de geração de vídeo, outro endpoint é mais adequado. Se isso corresponde ao seu caso de uso, continue lendo os pré-requisitos.

Pré-requisitos e obtenção da API Key

Antes de enviar a primeira requisição, confirme três coisas.

Conta HiAPI e API Key

Todas as requisições a este endpoint são autenticadas com uma API Key vinculada à sua conta HiAPI. Crie a Key no painel de controle da conta e evite commitá-la no controle de versão. Os exemplos abaixo a leem de uma variável de ambiente, para que você possa colá-la diretamente no terminal ou no script sem editar a chave inline:

export HIAPI_API_KEY="your_api_key_here"

Um cliente capaz de fazer requisições HTTPS

Para a parte em curl você precisa do curl, que já vem no macOS e na maioria das distribuições Linux. Para a parte em Python você precisa do Python 3 e da biblioteca requests (pip install requests). Não é necessário SDK específico de fornecedor — o endpoint é HTTPS comum com corpo JSON, então qualquer cliente HTTP serve, do fetch do Node ao httpx do Python.

Uma forma de armazenar estado entre requisições

Como a geração é assíncrona, você precisa de algum lugar para guardar o identificador de tarefa retornado pela chamada de envio — uma linha no banco de dados, uma fila de tarefas, um arquivo JSON durante os testes. Se você pretende usar callback em vez de polling, também precisa de um endpoint HTTPS acessível pela HiAPI.

Com a Key e um cliente funcional em mãos, você já pode enviar a requisição.

Enviando a primeira requisição funcional com curl

A chamada de envio é um POST com corpo JSON. O caminho exato do endpoint e o nome do cabeçalho de autenticação estão documentados na página do modelo — use esses valores como estão, sem inferi-los de outras APIs. A estrutura da chamada é esta:

curl -X POST "$HIAPI_BASE_URL/v1/models/seedance-2.5-flash/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
  }'

Algumas observações sobre cada parte:

  • Método e caminho. POST cria uma nova tarefa de geração. O caminho identifica o modelo; antes de copiá-lo para sua própria configuração, confirme-o na página do modelo.
  • Cabeçalhos. O cabeçalho Authorization carrega sua Key, e Content-Type: application/json informa ao servidor como interpretar o corpo da requisição.
  • Corpo. No mínimo, envie uma string prompt. O prompt é a entrada criativa — tudo o que o modelo renderiza vem dele, então especifique claramente o sujeito, o movimento, a iluminação e o comportamento da câmera.

Se a requisição for aceita, a resposta conterá um objeto de tarefa. Você não recebe a URL do vídeo imediatamente. Extraia o identificador da tarefa da resposta e guarde-o. Os nomes exatos dos campos fazem parte do schema de resposta documentado na página do modelo; trate-os como a única fonte de verdade e não codifique suposições no cliente antes de ver uma resposta real.

Você pode primeiro inspecionar a resposta bruta com curl e, depois de entender seu formato, mover a mesma chamada para o código.

Escolha de parâmetros: prompt, resolução e duração

Somente prompt é estritamente obrigatório, mas vários parâmetros opcionais determinam o resultado e o custo da requisição. Defina-os conscientemente em vez de aceitar os padrões às cegas.

Prompt

O prompt é o parâmetro de maior impacto. Escreva-o como se estivesse fazendo um briefing para um cinegrafista: sujeito, ação, ambiente, iluminação e estilo de câmera. "A cyclist weaving through a neon-lit Tokyo street at night, handheld camera, shallow depth of field" fornece ao modelo muito mais informação do que "a city". Mantenha o prompt dentro do limite de tamanho documentado na página do modelo.

Resolução

Resoluções mais altas significam mais detalhe e arquivos de saída maiores, e possivelmente tempos de geração mais longos. A geração de vídeo costuma ser cobrada pela duração da saída, mas confirme a base de cobrança atual e quaisquer faixas de resolução no painel de preços e na documentação do modelo, em vez de presumi-las. Escolha a menor resolução que atenda ao objetivo de entrega — ampliar depois geralmente sai mais barato do que gerar tudo na qualidade máxima.

Duração

A duração controla quantos segundos de vídeo o modelo gera e normalmente afeta tanto a latência quanto o custo. Clipes mais curtos são melhores para iterar: refine o prompt em durações curtas até o movimento ficar correto e depois gere novamente com o comprimento final.

Validação antes do envio

Antes de conectar os valores ao código de produção, consulte a página do modelo para conhecer as faixas permitidas de cada parâmetro — durações aceitas, resoluções suportadas e quaisquer valores de enumeração. Depois valide no cliente: rejeite durações fora da faixa e valores de resolução desconhecidos antes que a requisição saia do seu processo. Isso transforma uma classe de erros de validação do servidor em falhas imediatas e baratas nos seus próprios logs.

A mesma regra vale para os nomes dos parâmetros. Copie-os da documentação; um erro de digitação como um sublinhado a mais no campo de duração costuma ser rejeitado ou silenciosamente ignorado, e o silencioso é o bug mais difícil de encontrar.

Enviando a mesma requisição em Python

A seguir está o código de envio equivalente em Python. Ele lê a Key de uma variável de ambiente, envia o corpo JSON, verifica o código de status e retorna o identificador da tarefa a partir dos campos de resposta documentados.

import os
import requests

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


def submit_video(prompt: str, **options) -> str:
    payload = {
        "prompt": prompt,
        **options,  # e.g. resolution="720p", duration=5
    }
    response = requests.post(
        f"{BASE_URL}/v1/models/seedance-2.5-flash/text-to-video",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    body = response.json()
    task_id = body["id"]  # confirm the field name on the model page
    return task_id


if __name__ == "__main__":
    task_id = submit_video(
        "A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
    )
    print("submitted task:", task_id)

Há algumas escolhas intencionais neste código:

  • Timeout. A chamada de envio deve retornar rápido, mas um timeout explícito impede que um socket pendurado bloqueie seu worker.
  • raise_for_status(). Falhe imediatamente em erros HTTP, em vez de interpretar um corpo de resposta de erro como se fosse sucesso.
  • Opções por palavra-chave. Passar **options mantém o local da chamada legível e torna trivial adicionar resolution ou duration depois de confirmar os nomes exatos na página do modelo.
  • Retorno do ID. A responsabilidade da função termina no envio. Persista esse ID em algum armazenamento durável — a próxima seção o usará para buscar o resultado.

Em um pipeline real, trate submit_video como uma etapa em um fluxo orientado por fila: enfileire-o, salve o ID de tarefa retornado junto com o registro da sua tarefa e deixe um worker separado responsável por buscar o resultado.

Tratamento de resultados assíncronos: polling e callback

Após o envio você tem um ID de tarefa, mas ainda não tem o vídeo. Há duas formas de cobrir essa lacuna.

Polling

Consulte o endpoint de status da tarefa em intervalos fixos até a tarefa atingir um estado final e, então, obtenha a URL de saída a partir da resposta de conclusão.

import time
import requests


def wait_for_video(task_id: str, timeout_s: int = 600) -> dict:
    deadline = time.time() + timeout_s
    delay = 2.0
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/v1/tasks/{task_id}",  # confirm path on the model page
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()
        state = task["status"]
        if state == "completed":
            return task
        if state == "failed":
            raise RuntimeError(task.get("error", "generation failed"))
        time.sleep(delay)
        delay = min(delay * 1.5, 15)  # gentle backoff, capped
    raise TimeoutError(f"task {task_id} did not finish in time")

Três regras práticas para o polling:

  • Backoff. Comece com um atraso curto e aumente gradualmente. Polling contínuo em alta frequência desperdiça cota e adiciona carga sem nenhum benefício.
  • Defina um limite. Todo laço de polling precisa de um prazo final. A geração de vídeo pode demorar, mas um laço sem limite acabará deixando seu worker pendurado para sempre por causa de uma tarefa travada.
  • Diferencie os estados. Trate failed explicitamente, para que um prompt ruim não seja silenciosamente interpretado como timeout.

Callback

Se você registrar uma URL de callback HTTPS, a HiAPI pode notificá-lo quando a tarefa for concluída, evitando o polling por completo. Duas regras tornam os callbacks seguros e confiáveis:

  • Verifique antes de confiar. Trate o callback como entrada não autenticada até validar sua assinatura ou origem pelo mecanismo documentado na plataforma.
  • Seja idempotente. Um callback pode ser entregue mais de uma vez. Use o ID da tarefa como chave do handler e trate entregas repetidas como no-op — armazene o resultado apenas uma vez e confirme as entregas duplicadas.

Independentemente da abordagem escolhida, a obtenção do resultado é idempotente: buscar a URL de resultado de uma tarefa concluída deve retornar o mesmo vídeo, então repetir após um erro de rede é seguro.

Erros comuns e como corrigi-los

A maioria das falhas se resume a poucas categorias. Antes de supor um comportamento não documentado, percorra esta lista.

Falha de autenticação

401 ou 403 quase sempre significa que a Key está ausente, mal formatada ou expirada. Verifique se o cabeçalho Authorization existe, se o esquema de autenticação é exatamente o documentado e se a variável de ambiente realmente contém a Key — uma string vazia produz uma falha confusa, mas relacionada à autenticação.

Validação rejeitada

Um 4xx com mensagem de validação significa que o servidor rejeitou seus parâmetros. Releia as faixas permitidas na página do modelo e confirme os nomes dos parâmetros caractere por caractere. Se a duração ou a resolução estiver fora da faixa, a correção é a validação no cliente descrita anteriormente — falhe rápido no seu próprio código em vez de fazer uma ida e volta ao servidor.

Tarefa presa em estado não final

Se o polling nunca vê completed nem failed, a tarefa pode ainda estar em execução, ou seu laço de polling pode estar consultando o ID de tarefa errado. Registre o ID que você enviou e o ID que está consultando e compare-os. Seu laço também deve impor um prazo final; quando o prazo disparar, exponha o ID da tarefa em vez de tentar novamente às cegas.

O resultado não chega após o callback

Se você depende de callbacks, verifique se seu endpoint é acessível publicamente por HTTPS, se retorna um status de sucesso rapidamente em vez de executar trabalho pesado inline, e se entregas repetidas são tratadas de forma idempotente. Se o handler do callback falhar na segunda entrega da mesma tarefa, parecerá que o resultado se perdeu.

Reenvio da mesma tarefa

Se seu worker repete a chamada de envio após um timeout, pode criar tarefas duplicadas. Antes de chamar o endpoint, registre em seu próprio banco de dados uma chave de requisição do cliente ou ID de tarefa e verifique-a antes de tentar novamente, mantendo o envio idempotente do seu lado.

Princípio geral: quando ocorrer uma falha, leia o corpo da resposta de erro e a documentação do modelo antes de alterar o código. Se um valor ou campo não estiver documentado, evite supor que ele existe — valide na página do modelo e ajuste a requisição de acordo.

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