Framework de Avaliação da API Seedance para Equipes de Produto Text-to-Video

Uma avaliação da API Seedance deve responder a uma pergunta de produto, e não apenas produzir um clipe de demonstração impressionante. A decisão real é se a sua equipe consegue transformar prompts e mídias de referência em ativos de vídeo aceitáveis com qualidade, latência, segurança e custo previsíveis.

Em 29 de julho de 2026, a Flatkey lista seedance-2.5 como uma rota de acesso antecipado da ByteDance para geração de texto para vídeo e imagem para vídeo com saída em 1080p. O padrão atual de requisição é assíncrono: crie uma tarefa de vídeo com POST /v1/video/generations, guarde o ID da tarefa retornado e consulte GET /v1/videos/{task_id} até que o trabalho alcance um estado terminal.

Esse contrato de API é simples. Projetar uma avaliação da API Seedance útil é mais difícil. Este guia oferece a gerentes de produto e líderes de engenharia um conjunto de testes repetível, um cartão de pontuação com pesos, uma métrica de custo por clipe aceito e um plano de implementação de cinco dias.

Resposta rápida: o que uma avaliação da API Seedance deve medir?

Avalie a API em seis etapas:

1. Adequação de capacidade: Ela consegue produzir as cenas, o movimento, o enquadramento e a consistência de referência que o seu produto exige?
2. Repetibilidade: A mesma família de prompts produz resultados utilizáveis em múltiplas execuções?
3. Adequação ao fluxo de trabalho: Sua aplicação consegue lidar de forma limpa com tarefas assíncronas, polling, timeouts, armazenamento e novas tentativas?
4. Adequação à experiência do usuário: É possível definir expectativas honestas para espera, progresso, regeneração e falhas?
5. Adequação de segurança: Seu produto consegue impedir entradas proibidas e revisar saídas antes da distribuição?
6. Adequação de economia unitária: Quanto custa um clipe aceito depois de incluir trabalhos com falha e saídas rejeitadas?

Não aprove um provedor com base em uma única geração selecionada a dedo. Uma avaliação da API Seedance útil usa um conjunto fixo de prompts, execuções repetidas, pontuação às cegas e as mesmas regras de aceitação para cada modelo candidato.

Comece com o contrato atual da API Seedance

A página atual do modelo seedance-2.5 da Flatkey descreve uma rota de acesso antecipado com entrada por prompt, uma imagem opcional e uma URL MP4 como saída concluída. O exemplo da página cria uma tarefa de cinco segundos em 1080p:

curl -X POST https://router.flatkey.ai/v1/video/generations \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "content": [
      {
        "type": "text",
        "text": "Um avião de papel voando sobre uma cidade neon ao entardecer"
      }
    ],
    "resolution": "1080p",
    "duration": 5
  }'

Depois, consulte a tarefa usando o ID retornado:

curl https://router.flatkey.ai/v1/videos/TASK_ID \
  -H "Authorization: Bearer $FLATKEY_API_KEY"

Verifique a página do modelo Seedance 2.5 ao vivo antes da implementação, porque disponibilidade, campos da requisição e termos comerciais podem mudar durante o acesso antecipado.

Se a sua equipe ainda não verificou a chave e a URL base, conclua primeiro o quickstart da API Seedance existente. Use este artigo depois que a conectividade funcionar e a equipe de produto estiver pronta para avaliar se a rota se encaixa em um caso de uso real.

Defina um contrato de avaliação antes de gerar clipes

O passo de maior impacto em uma avaliação da API Seedance é chegar a um acordo sobre o contrato de aceitação antes que alguém veja os resultados. Caso contrário, as partes interessadas tendem a premiar qualquer clipe que pareça mais cinematográfico e a mudar discretamente seus critérios entre as execuções.

Registre estes campos:

O responsável pela aceitação deve estar próximo do fluxo de trabalho final. Um lead de criação de growth pode aprovar um clipe que uma equipe de renderização de produto rejeita porque a forma do produto mudou. Uma única pontuação universal de qualidade não pode representar todos os casos de uso.

Crie um conjunto de testes de 24 prompts para a API Seedance

Um conjunto de testes prático é grande o suficiente para expor padrões de falha, mas pequeno o bastante para ser repetido quando uma rota, um template de prompt ou um modelo muda. Comece com 24 prompts distribuídos em seis grupos.

Execute cada prompt pelo menos três vezes quando o orçamento permitir. Uma execução testa a possibilidade; execuções repetidas testam se o seu produto pode depender desse comportamento.

Mantenha os prompts neutros em relação ao provedor. Evite sintaxe de prompt que apenas um modelo entende, a menos que o próprio recurso faça parte da avaliação. Salve o prompt, os parâmetros da solicitação, o ID da tarefa, os timestamps, o status final, a URL de saída e as pontuações do avaliador para cada execução.

A pesquisa pública da Seedance da ByteDance enfatiza dimensões como aderência às instruções, qualidade do movimento, consistência temporal, narrativa em múltiplas cenas e qualidade visual. Essas são categorias úteis de avaliação, mas sua equipe deve traduzi-las em requisitos de produto observáveis, em vez de copiar diretamente um benchmark de pesquisa.

Use um scorecard de avaliação da API Seedance ponderado

O scorecard a seguir funciona como ponto de partida para produtos gerais de text-to-video. Altere os pesos antes de testar se seu caso de uso tiver prioridades diferentes.

Pontue cada dimensão de qualidade de 1 a 5, multiplique pelo respectivo peso e normalize o resultado para 100. Mantenha métricas operacionais, como latência e taxa de conclusão, medidas diretamente em vez de pontuadas de memória.

Para uma avaliação justa da API Seedance, os avaliadores não devem saber qual provedor produziu cada clipe quando você comparar vários modelos. Aleatorize os nomes de arquivo, remova os metadados do provedor da planilha de revisão e revele o modelo somente após a conclusão da pontuação.

Meça o custo por clipe aceito, não o custo por geração

A métrica de custo mais útil para geração de vídeo é:

custo por clipe aceito = gasto total de geração / clipes aceitos

Se 30 tarefas custam US$ 60 e apenas 12 saídas passam na revisão, o custo efetivo é de US$ 5 por clipe aceito — não US$ 2 por geração.

Também acompanhe:

taxa de aceitação = clipes aceitos / clipes concluídos

taxa de conclusão = clipes concluídos / tarefas enviadas

custo por ativo publicado = gasto total de geração / ativos realmente publicados

Isso impede que uma rota barata, mas inconsistente, pareça melhor do que uma rota mais cara que produz saídas utilizáveis com mais frequência. Também conecta a avaliação do modelo ao throughput criativo ou de produto real da equipe.

Atualmente, a Flatkey apresenta seedance-2.5 como acesso antecipado baseado em uso. Use o diretório de modelos e a página de preços ao vivo para obter informações comerciais atuais, em vez de copiar um número estático para uma planilha de planejamento.

Normalize o fluxo assíncrono por trás de um único adaptador

Seu produto não deve expor estados de tarefa específicos do provedor em toda a base de código. Coloque a API Seedance atrás de um pequeno adaptador de geração de vídeo e normalize o ciclo de vida.

type VideoJobState =
  | "queued"
  | "processing"
  | "succeeded"
  | "failed"
  | "expired";

type VideoJob = {
  id: string;
  state: VideoJobState;
  outputUrl?: string;
  errorCode?: string;
  submittedAt: string;
  completedAt?: string;
};

interface VideoGenerationAdapter {
  create(input: {
    prompt: string;
    imageUrl?: string;
    duration: number;
    resolution: string;
  }): Promise<VideoJob>;

  get(jobId: string): Promise<VideoJob>;
}

O adaptador deve preservar o ID da tarefa do provedor, o status terminal bruto, os parâmetros da requisição e os dados de uso para depuração. O restante do produto deve depender de estados normalizados.

Essa fronteira torna a avaliação da API Seedance mais honesta. Você pode comparar a qualidade e as operações da Seedance com outra rota de vídeo sem reescrever o fluxo do seu produto. Isso também oferece um ponto controlado para implementar intervalos de polling, limites de timeout, regras de retry, verificação de webhooks e lógica de migração.

Para um padrão de implementação mais profundo, veja o guia para uma URL base estável compatível com OpenAI para equipes usando a API Seedance. Antes do lançamento, execute a lista de verificação de produção da API Seedance separada para durabilidade da fila, idempotência, armazenamento e controles de incidente.

Mapeie o comportamento da API para a experiência do produto

Uma rota assíncrona de vídeo cria decisões de experiência do usuário que um endpoint de texto síncrono não cria.

Estado de espera

Mostre que a solicitação foi aceita e forneça uma referência durável da tarefa. Não sugira que um vídeo está quase pronto, a menos que a API exponha um progresso confiável.

Estado de timeout

Separe uma tarefa lenta de uma tarefa com falha. Um timeout do cliente não deve criar automaticamente uma segunda geração faturável. Continue verificando a tarefa original antes de permitir uma nova tentativa.

Regeneração

Permita que os usuários alterem uma variável por vez — prompt, imagem de referência, duração ou resolução — para que as equipes possam aprender por que um resultado melhorou ou piorou.

Revisão da saída

Armazene o prompt e os parâmetros ao lado do clipe. Forneça um estado de revisão interno antes que um recurso gerado possa entrar em um fluxo público ou voltado ao cliente.

Idioma de falha

Traduza as falhas do provedor em mensagens de produto acionáveis: entrada não suportada, rejeição por segurança, capacidade temporária, ativo expirado ou erro de serviço passível de nova tentativa. Preserve o código bruto para suporte e engenharia.

Inclua estes estados de UX na avaliação da API Seedance. Um modelo pode produzir clipes excelentes e ainda assim ser um mau encaixe para o produto se sua latência e seu comportamento em falhas não puderem ser comunicados de forma clara.

Adicione segurança e revisão de conteúdo à avaliação

As entradas e saídas de text-to-video devem passar por controles específicos do produto. No mínimo:

• validar o tipo, o tamanho e a origem da mídia de entrada;
• rejeitar solicitações obviamente não permitidas ou sem suporte antes de criar uma tarefa paga;
• registrar quem enviou a solicitação e qual versão da política foi aplicada;
• verificar por varredura ou revisar as saídas concluídas antes da distribuição pública;
• definir regras de retenção e exclusão para prompts, referências e arquivos gerados;
• impedir que um URL assinado temporário se torne o registro permanente de ativos do produto.

Não presuma que a camada de segurança de um provedor seja igual à política do seu produto. Sua aplicação continua responsável por decidir o que os usuários podem solicitar e qual conteúdo gerado pode ser armazenado, exibido ou publicado.

Execute uma avaliação de cinco dias com a equipe de produto

Dia 1: feche o contrato

Escolha o fluxo de trabalho, o responsável pela aceitação, 24 prompts, parâmetros, pesos de pontuação e orçamento máximo. Verifique o acesso atual na página do modelo Seedance 2.5.

Dia 2: implemente o adaptador

Crie tarefas, persista os IDs das tarefas, faça polling com segurança, normalize os estados e armazene as saídas. Confirme que uma sessão interrompida do cliente não faz o job se perder.

Dia 3: gere o conjunto fixo de testes

Execute o mesmo conjunto de prompts sob parâmetros controlados. Registre cada solicitação, incluindo falhas e saídas que os revisores rejeitem imediatamente.

Dia 4: pontue às cegas

Peça que pelo menos dois revisores classifiquem os clipes de forma independente. Calcule a taxa de aceitação, a taxa de conclusão, o p50 e o p95 de tempo até o estado terminal, a pontuação de qualidade ponderada e o custo por clipe aceito.

Dia 5: decida e documente

Aprove um dos quatro resultados:

1. Prosseguir para beta limitada para o fluxo de trabalho testado.
2. Prosseguir com restrições sobre tipos de prompt, duração, entradas de referência ou grupos de usuários.
3. Continuar a avaliação com prompts revisados ou uma amostra maior.
4. Não prosseguir porque qualidade, operações, segurança ou economia unitária não atingem o limite acordado.

Essa estrutura de cinco dias evita que uma avaliação da API Seedance se transforme em um experimento criativo sem fim.

Exemplos de limites de seguir/não seguir

Defina limites antes de testar. Uma equipe de produto hipotética pode exigir:

Estes são exemplos, não benchmarks universais. Uma ferramenta de storyboard pode tolerar menor fidelidade do que um fluxo de trabalho automatizado de anúncio de produto. O valor vem de pré-comprometer-se com limites mensuráveis.

O que torna esta avaliação reutilizável?

Versione em conjunto o conjunto de prompts, a scorecard, o adaptador e o conjunto de dados de resultados. Quando o acesso mudar ou uma nova rota do Seedance estiver disponível, execute novamente o mesmo pacote.

Guarde estes artefatos:

• versão do conjunto de prompts;
• versão do esquema da solicitação;
• ID do modelo e da rota;
• parâmetros de geração;
• carimbos de data e hora brutos do ciclo de vida da tarefa;
• IDs dos revisores e pontuações cegas;
• decisão de aceitação e motivo da rejeição;
• registro de custo e uso;
• versão da política;
• decisão final de ir/não ir.

Isso transforma a avaliação da API Seedance em um ativo durável de operações de modelo, em vez de um documento de lançamento pontual. A mesma estrutura também dá suporte a um roteamento mais amplo de modelos multimodais quando seu produto compara modelos de vídeo, imagem, áudio e linguagem por trás de uma única camada de acesso.

Recomendação final

Use a API Seedance quando ela passar pelo contrato de aceitação do seu fluxo de trabalho — não porque um clipe gerado pareça impressionante. Verifique a rota atual, teste um conjunto fixo de prompts, pontue as saídas às cegas, inclua falhas na economia unitária e mantenha o ciclo assíncrono por trás de um adaptador.

Para usuários da Flatkey, a sequência prática é:

1. verificar a chave e o roteador com o guia rápido da API Seedance;
2. confirmar o acesso atual ao seedance-2.5 e os campos da solicitação na página ao vivo do modelo;
3. executar a scorecard neste guia;
4. concluir a lista de verificação de produção antes da implementação para clientes.

Uma avaliação disciplinada da API Seedance fornece às equipes de produto, engenharia, criação, segurança e finanças uma resposta compartilhada: se a rota pode produzir de forma confiável vídeo aceitável para o fluxo de trabalho que você realmente planeja lançar.

Perguntas frequentes

A API Seedance é síncrona ou assíncrona?

O exemplo atual do seedance-2.5 da Flatkey usa um fluxo de trabalho assíncrono. A aplicação cria uma tarefa de vídeo, armazena o ID da tarefa retornado e consulta o endpoint da tarefa de vídeo para concluir.

Qual é a métrica mais importante de avaliação da API Seedance?

Para a maioria das equipes de produto, é o custo por clipe aceito, porque essa métrica inclui tanto o gasto de geração quanto a usabilidade da saída. Combine isso com taxa de aceitação, taxa de conclusão, latência e uma pontuação de qualidade ponderada.

Quantos prompts uma equipe de produto deve testar?

Vinte e quatro prompts em seis grupos de comportamento é um ponto de partida prático. Execute cada prompt várias vezes quando o orçamento permitir, para que a avaliação meça repetibilidade e não possibilidade.

Os revisores devem saber qual modelo produziu cada clipe?

Não, não ao comparar provedores ou versões de modelos. A revisão cega reduz a preferência pela marca e o viés de confirmação.

O Seedance 2.5 oferece suporte a imagem para vídeo?

A página de modelo ao vivo da Flatkey atualmente lista seedance-2.5 para texto para vídeo e imagem para vídeo com uma entrada opcional de imagem. Confirme a rota e os campos atuais antes da implementação, pois ela está marcada como acesso antecipado.

Um produto deve tentar novamente automaticamente uma solicitação de vídeo que expirou por timeout?

Não criando imediatamente uma nova tarefa. Primeiro, verifique o ID da tarefa existente. Um timeout no cliente não prova que a tarefa do provedor falhou, e uma nova submissão automática pode criar trabalho e custo duplicados.

Quando uma avaliação da API Seedance está completa?

Ela está completa quando a equipe mediu qualidade, repetibilidade, confiabilidade de conclusão, tempo até um resultado utilizável, tratamento de segurança e custo por clipe aceito em relação às métricas acordadas antes dos testes.