Como usar a API do Seedance 2.5: um guia rápido

Você pode ir da chave de API ao MP4 finalizado em quatro passos: envie uma solicitação POST autenticada, salve o request_id, faça polling do endpoint de resultado a cada 10 a 20 segundos e baixe o vídeo antes que o link expire, muitas vezes dentro de 24 horas.

Se eu quisesse a versão curta, aqui está o que eu manteria em mente:

• Use o endpoint certo
  • seedance-2.5-text-to-video para prompts de texto
  • seedance-2.5-image-to-video para animar uma URL de imagem pública
• Envie os cabeçalhos certos
  • Authorization: Bearer <API_KEY>
  • Content-Type: application/json
• Escolha as principais configurações de saída
  • resolution: 480p a 4K
  • aspect_ratio: como 16:9 ou 9:16
  • duration: até 16 segundos
  • generate_audio: true para som e falas
• Faça polling em vez de reenviar
  • Verifique predictions/{request_id}/result
  • Observe queued, running, succeeded ou failed
• Controle o custo
  • Comece em 480p ou 720p
  • Mantenha o mesmo seed
  • Reexecute em 1080p ou 4K apenas quando o plano parecer certo

Eu também ficaria atento aos pontos de falha mais comuns: 401 de um cabeçalho de autenticação ruim, 402 por falta de créditos, 429 por jobs ativos demais e 400 de JSON ruim ou campos ausentes. Na APIMart, os créditos são reservados quando uma tarefa começa e cobrados apenas se ela termina; tarefas com falha são reembolsadas.

Se você está escolhendo entre modelos, o Seedance 2.5 é a opção de topo desta linha: até 16s, até 3.840 × 2.160 e até 50 entradas de referência. O Seedance 2.0 fica no meio, e o Seedance 2 Mini é melhor para rascunhos de menor custo.

Resumindo: se você consegue fazer uma solicitação POST válida e armazenar um ID, você consegue rodar todo o fluxo de trabalho. O resto é ajuste de prompt, polling paciente e download do arquivo antes que a URL expire. Para pós-processamento, você pode usar o AI Canvas para dar upscale ou editar seus clipes gerados.

Passo 1: configure o acesso à APIMart e autentique as solicitações

Toda solicitação do Seedance 2.5 precisa de uma chave de API válida e dos cabeçalhos certos. Comece por aí. Uma vez que isso esteja no lugar, você pode passar para os payloads de geração de vídeo e o rastreamento de tarefas.

Crie e armazene sua chave de API com segurança

Crie sua chave no painel da conta, em Settings ou API Keys. Depois armazene-a em um arquivo .env ou em uma variável de ambiente, não no controle de versão ^[6][8].

export APIMART_API_KEY="sk_live_xxxxxx"

Se a chave for perdida, revogue-a e crie uma nova ^[3]. Para testes de integração, use uma chave sk_test_ separada para não tocar no uso de produção ^[3].

Em seguida, inclua essa chave em cada solicitação com o cabeçalho Authorization.

Adicione o cabeçalho Authorization corretamente

Envie as solicitações para https://muapi.ai/api/v1/ com estes cabeçalhos:

• Authorization: Bearer sk_live_xxxxxx
• Content-Type: application/json

Um pequeno deslize de formatação pode quebrar a solicitação. O mais comum é deixar de fora o prefixo Bearer ou omitir o espaço antes da chave ^[3][7]. Isso geralmente leva a uma resposta 401 Unauthorized. Deixar de fora o Content-Type: application/json também pode fazer a solicitação falhar ^[3][7].

Com a autenticação configurada, você pode passar para o payload da solicitação de vídeo.

Passo 2: monte uma solicitação de geração de vídeo do Seedance 2.5

Com sua chave de API configurada, o próximo passo é montar um corpo de solicitação válido. Toda tarefa do Seedance 2.5 começa com uma solicitação POST para um de dois endpoints, com base no que você está usando como ponto de partida. Use https://muapi.ai/api/v1/seedance-2.5-text-to-video para geração apenas por prompt, ou https://muapi.ai/api/v1/seedance-2.5-image-to-video se você está animando uma imagem de origem ^[1].

Escolha o modo de entrada e os parâmetros certos

Seu modo de entrada determina o formato do payload. Texto para vídeo só precisa de um prompt. Imagem para vídeo também precisa de uma image_url que aponte para um arquivo JPG, PNG ou WEBP publicamente acessível e com menos de 10 MB ^[1].

A partir daí, você controla a saída com alguns campos principais:

• resolution: 480p, 720p, 1080p ou 4K
• aspect_ratio: 16:9, 9:16, 1:1, 4:3, 3:4 ou 21:9
• duration: até 16 segundos no Muapi
• generate_audio: um booleano que ativa som ambiente sincronizado, efeitos e diálogo quando definido como true ^[1]

Uma maneira inteligente de trabalhar é começar em 480p com um seed fixo. Se o movimento, o ritmo e o enquadramento parecerem certos, rode esse mesmo seed novamente em 1080p ou 4K para a versão final.

Para prompts, use este fluxo: Sujeito → Ação → Câmera → Cenário → Clima ^[4]. Mantenha movimento, direção de câmera e clima dentro do próprio prompt, e deixe o seed inalterado enquanto você testa variações. Se você precisa de sincronização labial, coloque a fala entre aspas duplas dentro da string do prompt. Por exemplo: she turns and says "We launch at dawn." Nesse caso, certifique-se de que generate_audio esteja definido como true ^[1].

Uma vez que o payload esteja bom, envie a tarefa e salve o ID de solicitação retornado. Você vai precisar dele para o polling.

Solicitações de exemplo em cURL, Postman, Python e JavaScript

Abaixo está o mesmo payload de texto para vídeo mostrado em quatro ferramentas comuns.

cURL

curl -X POST https://muapi.ai/api/v1/seedance-2.5-text-to-video \
  -H "Authorization: Bearer $APIMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": true,
    "seed": 42
  }'

Postman - Crie uma nova solicitação POST, cole a URL do endpoint, adicione Authorization: Bearer <your_key> e Content-Type: application/json na aba Headers, depois cole o JSON acima em Body → raw → JSON. Clique em Send e salve o request_id da resposta.

Python

import os, requests

payload = {
    "prompt": "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": True,
    "seed": 42
}

response = requests.post(
    "https://muapi.ai/api/v1/seedance-2.5-text-to-video",
    headers={
        "Authorization": f"Bearer {os.environ['APIMART_API_KEY']}",
        "Content-Type": "application/json"
    },
    json=payload
)

print(response.json())  # save request_id here

JavaScript (fetch)

const response = await fetch("https://muapi.ai/api/v1/seedance-2.5-text-to-video", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.APIMART_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    aspect_ratio: "16:9",
    resolution: "1080p",
    duration: 8,
    generate_audio: true,
    seed: 42
  })
});

const data = await response.json();
console.log(data.request_id); // use this to poll for results

Alguns erros podem atrapalhar você rápido. Não envie uma image_url que não seja publicamente acessível. Não empilhe direções de câmera que conflitem entre si no mesmo prompt. E no modo imagem para vídeo, não descreva um sujeito novamente se a imagem de origem já o define ^[1].

Após o envio, faça polling do status da tarefa até que a URL do MP4 esteja pronta.

Quando usar o Seedance 2.5 na linha de modelos de vídeo da APIMart

Esta comparação rápida ajuda você a escolher o modelo certo antes de começar a ajustar prompts ou aumentar a resolução. O Seedance 2.5 dá a você 4K nativo, até 50 entradas de referência e suporte a clipes mais longos. O Seedance 2 Mini é melhor para rascunhos leves, enquanto o Seedance 2.0 fica no meio como a opção de uso geral ^[1][9][4].

Se o projeto é um entregável final - como um vídeo de lançamento de produto, uma sequência cinematográfica de marca ou qualquer coisa destinada à transmissão - o Seedance 2.5 é a melhor escolha. Para projetos que exigem 高品質音声付きAI動画生成, o Veo 3.1 do Google é outro forte concorrente. Se você ainda está testando ideias, comece com o Mini para verificar o movimento e travar o enquadramento a um custo menor, e depois suba para o 2.5 para a renderização final.

Passo 3: envie a tarefa, acompanhe o status e leia a resposta

Uma vez que você envia a solicitação POST, a API retorna um request_id. Salve-o. Você vai usar esse ID para verificar a tarefa depois, porque a geração roda de forma assíncrona.

Lide com tarefas assíncronas da criação à conclusão

Depois de enviar a tarefa, o próximo passo é simples: faça polling até que o vídeo final esteja pronto.

Envie uma solicitação GET para https://muapi.ai/api/v1/predictions/{request_id}/result. Espere cerca de 10 segundos após o envio antes do primeiro polling, depois verifique novamente a cada 10–20 segundos. Se você fizer polling com mais frequência do que a cada 5 segundos, pode atingir limites de taxa ^[1][3].

Cada resposta inclui um campo status. Esse campo diz o que está acontecendo e o que você deve fazer em seguida:

Uma vez que a tarefa chega a succeeded, pegue a URL de saída antes que ela expire.

Leia os campos de saída e salve os resultados

Quando o status muda para succeeded, leia o payload de saída e armazene o resultado.

Uma resposta bem-sucedida inclui video_url. Ela também pode incluir last_frame_url se você pediu por ele. Salve video_url, o opcional last_frame_url e metadados como seed, duration, resolution, aspect_ratio e usage. Esses dados importam para a cobrança e para reproduzir a mesma execução depois ^[11][13].

As URLs de saída muitas vezes expiram dentro de 24 horas, então baixe o arquivo para o seu próprio armazenamento imediatamente ^[11][12][13]. Se uma tarefa falhar, registre error.code e error.message. E se a falha estiver ligada a verificações de segurança, não a repita automaticamente ^[2][11][12].

Passo 4: solucione erros, controle o custo e conclua

Corrija erros de autenticação, validação e limite de taxa

Depois de enviar uma tarefa e fazer polling dos resultados, algumas verificações simples podem evitar que as execuções de produção saiam dos trilhos. A maioria das falhas do Seedance tende a aparecer no mesmo punhado de formas.

Para ativos de referência, certifique-se de que a URL seja pública, que o arquivo seja JPG, PNG ou WEBP e que permaneça abaixo do limite de tamanho listado ^[12][4].

Reduza custos e melhore a confiabilidade

Uma vez que o tratamento de erros esteja configurado, o próximo passo é simples: teste barato, depois renderize grande.

Comece seu prompt em 480p ou 720p. Isso dá a você uma maneira de baixo custo de verificar enquadramento, movimento e se o prompt está fazendo o que você quer. Se o plano parecer certo, reexecute o mesmo valor de seed em 4K para a saída final ^[1][4].

A duração do clipe também importa. Vídeos mais curtos custam menos, então mantenha a duração no mínimo que ainda faz o trabalho ^[1][10].

Há também uma maneira sorrateira pela qual as equipes queimam dinheiro: envios duplicados após um timeout de rede. Uma correção limpa é gerar um hash do prompt, do ID do modelo e das URLs de mídia antes de cada solicitação POST. Se esse hash já mapeia para um ID de tarefa, pule o novo envio por completo ^[11]. E uma vez que uma tarefa chega a succeeded, salve o arquivo finalizado em armazenamento durável para não depender do registro da tarefa depois ^[12][11].

Conclusão: dos docs da API à geração de vídeo funcionando

Com autenticação, payloads, polling e tratamento de erros no lugar, você agora tem um fluxo completo do Seedance 2.5 na APIMart.

Perguntas frequentes

Quanto tempo o Seedance 2.5 leva para finalizar um vídeo?

O Seedance 2.5 pode gerar um clipe de vídeo contínuo de até 30 segundos de duração. A documentação, porém, não lista um tempo exato de conclusão.

A API roda de forma assíncrona. Você envia uma tarefa, recebe um ID de tarefa e depois faz polling do endpoint de status ou aguarda um webhook para obter o vídeo finalizado.

O tempo de processamento pode variar com base em coisas como resolução e complexidade da cena.

O que devo fazer se minha URL de vídeo expirar antes de eu baixá-lo?

Se a sua URL de vídeo expirar antes de você baixá-lo, você não conseguirá obter o arquivo a partir desse link. O Seedance mantém essas URLs temporárias ativas por 24 horas.

A jogada segura é simples: copie o vídeo para o seu próprio armazenamento de objetos seguro assim que a tarefa aparecer como concluída. Como a API roda de forma assíncrona e não guarda a saída para sempre, seu app deve buscar o vídeo e movê-lo para armazenamento de longo prazo imediatamente.

Como posso evitar cobranças duplicadas ao repetir solicitações com falha?

Use tratamento idempotente de solicitações vinculado aos seus próprios registros duráveis de tarefas, não apenas ao cliente HTTP.

Antes de enviar qualquer coisa, monte um hash de solicitação determinístico a partir de entradas como o prompt, o ID do modelo, os IDs dos ativos e o identificador do usuário. Depois salve esse hash com um status submitting no seu próprio banco de dados.

Se esse mesmo hash aparecer novamente, retorne a tarefa existente em vez de criar uma nova.

Uma vez que você armazenou um ID de tarefa do provedor, não envie a solicitação de novo. Apenas retome o polling com esse ID de tarefa.