Checklist de produção da API Seedance para equipes de texto para vídeo

Um protótipo da API Seedance pode parecer pronto após um único vídeo bem-sucedido. Uma integração em produção só está concluída quando o seu sistema consegue suportar trabalhos lentos, eventos duplicados, rotas de modelo em mudança, falhas parciais e custo incerto.

Essa diferença importa porque a geração de vídeo não é um recurso normal de solicitação-resposta. A aplicação envia o trabalho, aguarda, recebe mudanças de status, armazena uma grande saída e decide se uma falha deve ser tentada novamente. A chamada ao modelo é apenas uma etapa em um fluxo de trabalho mais longo.

Esta checklist transforma esse fluxo de trabalho em um contrato de produção que suas equipes de produto, plataforma e finanças podem revisar juntas.

Nota sobre a rota atual: O catálogo público de modelos da Flatkey listava seedance-2.5 para texto para vídeo e imagem para vídeo, além de seedance-2.0-i2v para imagem para vídeo, quando este guia foi verificado em segunda-feira, 27 de julho de 2026. Trate esses nomes como estado do catálogo, não como constantes permanentes. Confirme o diretório de modelos da Flatkey atual antes de colocar em produção ou alterar uma lista de अनुमति.

A resposta curta

Não conecte sua solicitação voltada ao usuário diretamente a uma chamada de provedor de vídeo. Coloque uma camada de trabalho durável entre elas.

Seu caminho mínimo de produção deve ser:

1. aceitar e validar a solicitação de geração do usuário
2. atribuir sua própria chave de idempotência e ID do trabalho
3. armazenar a solicitação antes de chamar a rota do modelo
4. enviar o trabalho por meio de um adaptador no lado do servidor
5. processar atualizações de webhook e polling de forma idempotente
6. copiar a mídia concluída para um armazenamento que você controla
7. registrar latência, motivo da falha, rota do modelo e custo estimado
8. expor um status de produto estável, independente da terminologia do provedor

Se uma dessas etapas estiver faltando, a integração ainda pode funcionar bem em uma demonstração, mas é mais difícil operá-la com segurança.

Por que o trabalho de produção da API Seedance é diferente

A geração de texto frequentemente retorna uma resposta útil em uma única troca HTTP. A geração de vídeo geralmente se comporta como um trabalho em lote distribuído. Uma ação do usuário pode ultrapassar a duração de uma solicitação da aplicação, um deploy, uma sessão do navegador ou até mesmo a URL temporária que eventualmente armazena o resultado.

As consequências práticas são fáceis de subestimar:

O objetivo não é ocultar o provedor. É evitar que o comportamento específico do provedor se torne o contrato permanente do seu produto.

1. Congele o contrato do produto antes do payload

Comece pela experiência que você promete aos usuários, e não pelos campos do provedor disponíveis hoje.

Defina:

• tipos de entrada aceitos: apenas texto, imagem mais texto, ou ambos
• formatos de proporção e faixas de duração suportados
• tamanho máximo de upload e formatos de mídia aceitos
• verificações de moderação e direitos antes do envio
• atualizações de status esperadas e comportamento de cancelamento
• período de retenção da saída
• se um job com falha consome um crédito do usuário
• o que “retry” significa no produto

Depois, traduza esse contrato para a rota atual do Seedance dentro de um adaptador.

Essa separação protege você de dois modos de falha comuns. Primeiro, uma atualização de rota pode adicionar ou renomear parâmetros sem forçar uma reescrita do frontend. Segundo, sua aplicação pode rejeitar combinações não suportadas antes de gastar dinheiro em um job fadado ao fracasso.

2. Use seu próprio ID de job e chave de idempotência

Toda solicitação precisa de dois identificadores:

• ID do job do produto: o identificador estável exibido em todo o seu sistema
• chave de idempotência: o identificador usado para evitar envio duplicado acidental

Não use um ID de tarefa do provedor como sua chave primária. Ele não existe até depois do envio e pode mudar se você reenviar deliberadamente por outra rota.

Um registro simples de solicitação pode ser assim:

type VideoJob = {
  id: string;
  idempotencyKey: string;
  accountId: string;
  requestedModel: string;
  resolvedModel: string | null;
  providerTaskId: string | null;
  status: "accepted" | "queued" | "running" | "succeeded" | "failed" | "cancelled";
  attempt: number;
  outputUrl: string | null;
  failureCode: string | null;
  createdAt: string;
  updatedAt: string;
};

Crie esse registro antes da chamada de API de saída. Se a aplicação travar após o envio, mas antes de salvar a resposta, a chave de idempotência lhe dá uma forma de reconciliar em vez de cobrar cegamente por outra geração.

3. Coloque o Seedance atrás de um único adaptador do lado do servidor

Mantenha a construção de requisições específica do provedor em um único módulo. O restante do seu produto deve enviar um comando normalizado, como:

type GenerateVideoCommand = {
  prompt: string;
  sourceImageUrl?: string;
  aspectRatio: "16:9" | "9:16" | "1:1";
  durationSeconds: number;
  qualityProfile: "draft" | "standard" | "high";
};

O adaptador é responsável por:

• resolver qualityProfile para um modelo e configurações atualmente disponíveis
• adicionar autenticação no lado do servidor
• traduzir suas escolhas de aspecto e duração para o esquema de API ativo
• enviar a tarefa
• normalizar erros do provedor
• armazenar o ID da tarefa do provedor
• reportar metadados suficientes para análise de custo e confiabilidade

A Flatkey oferece às equipes uma chave de API, um endpoint roteador estável, um saldo compartilhado e visibilidade centralizada de uso entre famílias de modelos. Para equipes que já usam essa camada de acesso, mantenha a lógica assíncrona específica do Seedance no adaptador, em vez de espalhar suposições de rota pelo codebase. O guia anterior sobre uma URL base estável compatível com OpenAI para equipes da API Seedance explica essa fronteira com mais detalhes.

4. Modele o fluxo de trabalho como uma máquina de estados

Não deixe strings de status arbitrárias entrarem na lógica do produto. Normalize-as.

stateDiagram-v2
    [*] --> accepted
    accepted --> queued: submit accepted
    accepted --> failed: validation or submit error
    queued --> running: provider starts work
    queued --> failed: terminal provider error
    running --> succeeded: output verified
    running --> failed: terminal provider error
    accepted --> cancelled: cancelled before submit
    queued --> cancelled: cancellation confirmed
    succeeded --> [*]
    failed --> [*]
    cancelled --> [*]

Permita apenas transições para frente, a menos que você esteja executando um processo explícito de recuperação. Um evento running tardio não deve sobrescrever um job já marcado como succeeded. Um webhook succeeded duplicado não deve acionar duas cópias de armazenamento nem duas notificações ao cliente.

Armazene o evento bruto do provedor separadamente para depuração, mas tome as decisões do produto a partir do estado normalizado.

5. Use webhooks e polling juntos

Webhooks são eficientes, mas não garantem que sua aplicação processe cada evento uma vez e em ordem. Polling é mais lento, mas é valioso para reconciliação.

Use ambos:

• caminho de webhook: atualizações de status de baixa latência
• caminho de polling: recuperação agendada para jobs que não mudaram recentemente

Seu manipulador de webhook deve:

1. autenticar o callback quando a API ativa oferecer suporte à verificação
2. analisar o evento sem fazer trabalho pesado inline
3. escrever uma impressão digital do evento em uma tabela de deduplicação
4. enfileirar o processamento
5. retornar sucesso rapidamente

Seu worker de reconciliação deve fazer polling apenas de jobs que ainda não são terminais após um atraso sensato. Adicione jitter para que uma implantação não cause milhares de verificações de status no mesmo instante.

Os campos de webhook e de consulta específicos do fornecedor podem mudar. Verifique-os na referência oficial atual da API durante a implementação, em vez de copiar um payload antigo de um post de blog.

6. Tome decisões de retry por classe de falha

“Repetir jobs com falha” não é uma política. É um risco de custo.

Normalize os erros em classes:

A última distinção é especialmente importante. Se o vídeo foi gerado com sucesso, mas sua cópia para o armazenamento falhou, regenerar o vídeo cria custo desnecessário e pode produzir um resultado diferente.

Defina um orçamento de retry por job. Uma política razoável pode permitir mais verificações de status e tentativas de cópia para armazenamento do que submissões de geração.

7. Copie os resultados para um armazenamento que você controla

Trate qualquer URL de resultado hospedada pelo provedor como um local de transferência, não como seu ativo permanente do produto.

Depois que um job for bem-sucedido:

1. verifique se a resposta contém o tipo de mídia esperado
2. faça o download com um limite de tamanho e de tempo
3. valide que o arquivo não está vazio nem obviamente truncado
4. calcule um checksum
5. copie-o para seu armazenamento de objetos
6. salve duração, dimensões, codec e tamanho
7. altere o job do produto para succeeded somente depois que a cópia durável estiver disponível

Se o seu produto permitir que os usuários baixem o ativo original do provedor antes que a cópia termine, represente isso como um estado transitório separado. Não prometa permanência silenciosamente.

8. Adicione controles de custo antes de abrir o recurso

Jobs de vídeo são caros o suficiente para que limites de produto existam antes do lançamento público.

No mínimo, defina:

• um limite de gasto por chave ou por equipe
• uma allowlist de modelos para a chave da aplicação
• máximo de jobs simultâneos por conta
• duração máxima e perfil de qualidade por plano
• um limite diário de submissão para contas novas ou não confiáveis
• um circuit breaker quando a taxa de falhas ou o custo por sucesso subir

A documentação pública da Flatkey descreve limites por chave, allowlists opcionais de modelos e visibilidade de uso por meio de Usage & Logs ou da API de ledger. Use esses controles como a proteção da camada de acesso e, depois, adicione quotas no nível do produto com base nos seus próprios planos e no risco de abuso.

Antes de habilitar uma nova rota, compare o catálogo atual e os preços da Flatkey. Não incorpore um preço numérico deste artigo na lógica da aplicação; preços e disponibilidade de rotas são dados atualizáveis.

9. Meça o job completo, não apenas a latência da API

Para um fluxo de trabalho assíncrono da API Seedance, um envio bem-sucedido ainda pode resultar em uma experiência ruim para o cliente.

Acompanhe pelo menos:

• taxa de aceitação de envios
• tempo de espera na fila
• tempo de geração
• tempo total até a saída durável
• taxa de sucesso por modelo resolvido
• taxa de falha por classe de falha normalizada
• atraso na entrega de webhook
• taxa de recuperação por polling
• taxa de falha na cópia para armazenamento
• custo por job enviado
• custo por saída durável bem-sucedida
• contagem de prevenção de envios duplicados

Use percentis, não apenas médias. Um tempo mediano de geração pode parecer saudável enquanto os dez por cento mais lentos dos jobs geram a maioria dos tickets de suporte.

Registre também requestedModel e resolvedModel separadamente. Isso torna as mudanças de rota visíveis e fornece evidências para decisões de rollback.

10. Entregue mudanças de modelo como migrações

Uma mudança de catálogo não é apenas uma substituição de string. Trate-a como uma atualização de dependência.

Antes de mover o tráfego de produção para uma nova rota Seedance:

1. confirme a rota atual no diretório de modelos ativo
2. compare as entradas suportadas e as restrições de saída
3. execute um conjunto fixo de avaliação em seus tipos de prompt mais comuns
4. compare taxa de sucesso, latência, aceitação da saída e custo
5. teste webhook, polling e normalização de erros
6. faça canary em uma pequena porcentagem do tráfego
7. preserve uma rota de rollback até que o canary esteja estável
8. atualize a allowlist de modelos e o runbook operacional

Se sua aplicação expõe uma configuração de “qualidade”, mapeie-a para um perfil de capacidade em vez de um ID de modelo permanente. Isso permite alterar a rota de backend sem quebrar a API do produto.

Checklist de prontidão para produção

Use esta lista como um gate de lançamento.

Solicitação e acesso

• [ ] as chaves de API permanecem no servidor
• [ ] a chave da aplicação tem um limite de gastos e uma allowlist de modelos
• [ ] toda solicitação tem um ID interno de job e uma chave de idempotência
• [ ] as entradas são validadas antes do envio
• [ ] a rota atual do modelo Seedance é verificada no catálogo ativo

Execução assíncrona

• [ ] a lógica específica do provedor vive em um único adaptador
• [ ] os status do produto usam uma máquina de estados normalizada
• [ ] os eventos de webhook são autenticados quando suportados e deduplicados
• [ ] o polling reconcilia jobs não terminais obsoletos
• [ ] eventos tardios ou duplicados não podem reverter estados terminais

Confiabilidade e custo

• [ ] o comportamento de retry varia conforme a classe de falha
• [ ] as tentativas de geração têm um orçamento estrito
• [ ] as tentativas de cópia da saída não regeneram vídeos bem-sucedidos
• [ ] os limites de concorrência e de jobs diários são aplicados
• [ ] um circuit breaker pode pausar uma rota degradada

Saída e observabilidade

• [ ] mídia bem-sucedida é copiada para armazenamento controlado
• [ ] metadados de saída e checksum são armazenados
• [ ] os IDs do modelo solicitados e resolvidos são registrados
• [ ] o custo por saída durável bem-sucedida é medido
• [ ] os operadores têm um runbook para trabalhos travados, com falha e duplicados

Onde a Flatkey se encaixa

A Flatkey não elimina a necessidade de uma camada assíncrona de jobs de vídeo. Ela reduz o trabalho de acesso e governança em torno dessa camada: uma conta, um saldo, controles de chave de API, uma superfície de roteador estável, um catálogo de modelos ao vivo e registros centralizados de uso.

Para uma primeira integração, comece com o quickstart da API Seedance para equipes de produto de texto para vídeo. Quando o recurso avançar em direção à produção, aplique esta checklist às camadas de fila, estado, retry, armazenamento e observabilidade ao redor da chamada ao modelo.

Se sua equipe estiver decidindo qual rota atual e quais controles de uso se encaixam no lançamento, revise os modelos ao vivo e os preços antes de aprovar a configuração de produção.

Perguntas frequentes

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

Trate a geração de vídeo como um job assíncrono. Seu produto deve enviar o trabalho, retornar seu próprio ID de job e processar atualizações de status por meio de webhooks e/ou polling de acordo com a referência atual da API.

Devo usar um ID de tarefa do provedor como chave primária do meu banco de dados?

Não. Crie seu próprio ID de job estável antes do envio. Armazene o ID de tarefa do provedor como uma referência externa para que você possa reconciliar, reenviar ou alterar rotas sem mudar o identificador do produto.

Preciso de webhooks e polling?

Para um sistema de produção resiliente, sim. Webhooks fornecem atualizações rápidas; o polling recupera jobs cujos eventos foram atrasados, perdidos ou não processados.

Quando é seguro tentar novamente um job Seedance com falha?

Tente novamente apenas após classificar a falha. Falhas de capacidade e de rede podem ser passíveis de retry. Falhas de validação, autenticação, segurança ou outras falhas terminais normalmente exigem uma alteração de configuração ou do usuário. Se o envio expirou, reconcilie por chave de idempotência antes de enviar outro job pago.

Devo armazenar o vídeo gerado eu mesmo?

Sim. Copie a saída concluída para o armazenamento sob seu controle, valide o arquivo e salve seus metadados. URLs de resultados hospedadas pelo provedor não devem ser tratadas como armazenamento permanente do produto, a menos que os termos atuais garantam explicitamente esse comportamento.

Como devo lidar com uma nova versão do modelo Seedance?

Trate isso como uma migração: verifique o catálogo atual, execute um conjunto fixo de avaliação, compare qualidade, latência, falhas e custo, direcione tráfego em canary e preserve um caminho de rollback até que a mudança esteja estável.

Qual modelo Seedance devo codificar de forma fixa?

Evite codificar permanentemente um modelo com base em um artigo estático. Resolva um perfil de capacidade do produto para um modelo listado no atual diretório de modelos da Flatkey e mantenha a rota escolhida na configuração para que os operadores possam alterá-la com segurança.