API Seedance para equipes de produto de texto para vídeo

Se a sua equipe de produto quer a forma mais rápida e segura de avaliar o acesso à Seedance API, o primeiro passo certo não é construir o fluxo completo de vídeo no primeiro dia. É comprovar três fundamentos com a menor superfície de integração possível:

1. sua chave Flatkey autentica corretamente
2. sua aplicação consegue chamar https://router.flatkey.ai/v1
3. sua equipe consegue ver a requisição em Usage Logs antes de conectar os jobs assíncronos de vídeo

Esse é o quickstart de baixo atrito que esta página cobre.

A partir de sexta-feira, 17 de julho de 2026, o quickstart público da Flatkey ainda orienta os desenvolvedores a usar Bearer auth, a URL base compatível com OpenAI https://router.flatkey.ai/v1 e POST /v1/chat/completions para o primeiro teste de fumaça. O catálogo de modelos ao vivo da Flatkey também lista publicamente 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. A própria página pública de API da Seedance ainda descreve o fluxo de vídeo como criação assíncrona de tarefas, sondagem de status, webhooks e créditos baseados no uso.

Essa combinação importa para o onboarding: o padrão de acesso ao router é simples, mas o fluxo real de geração de vídeo não é uma chamada de chat síncrona. As equipes de produto devem validar o router primeiro com a menor requisição possível e, depois, trocar apenas o modelo e o fluxo de job de que precisam para a avaliação da Seedance.

Resposta rápida

Use esta sequência quando quiser um caminho de onboarding da Seedance que possa ser revisado com o menor número possível de partes móveis.

Etapa	O que usar	O que isso prova
1. Criar uma chave	Chave de API Flatkey começando com sk-fk-	Sua equipe tem uma credencial válida
2. Definir uma única URL base	https://router.flatkey.ai/v1	Sua aplicação aponta para o router compartilhado, e não para um endpoint específico do provedor
3. Executar o menor teste de fumaça	POST /v1/chat/completions com um modelo de texto simples	Autenticação, cabeçalhos, roteamento e Usage Logs funcionam
4. Trocar para a rota da Seedance	Substituir o modelo placeholder pelo ID do modelo Seedance aprovado	A mesma camada de acesso agora pode suportar seu fluxo de avaliação de vídeo
5. Adicionar tratamento assíncrono	Lógica de polling ou webhook para jobs de vídeo	Seu produto está pronto para a execução real de texto para vídeo

Se você só lembrar de uma coisa, lembre-se disto: a primeira requisição cURL é uma verificação de conectividade com o router, não o payload final de texto para vídeo.

Antes de começar

Você precisa de quatro coisas:

• Uma conta Flatkey
• Uma chave de API Flatkey
• Algum crédito pré-pago para a requisição
• Uma decisão de produto sobre qual rota da Seedance você realmente quer avaliar

Para a maioria das equipes de texto para vídeo, o catálogo público de modelos torna as opções atuais claras o suficiente para iniciar a conversa:

Sinal público atual de modelo na Flatkey	Melhor uso
seedance-2.5	Avaliação de texto para vídeo, além de imagem para vídeo, se necessário
seedance-2.0-i2v	Apenas imagem para vídeo

Não fixe em código um nome de modelo retirado de uma captura de tela antiga ou de uma nota interna. Verifique o diretório de modelos atual ou o catálogo ao vivo no dia da publicação, porque a disponibilidade das rotas de vídeo pode mudar mais rápido do que um guia de configuração estático.

Etapa 1: crie e armazene a chave de API da Flatkey

No Flatkey Console, crie uma chave de API e armazene-a como uma variável de ambiente.

export FLATKEY_API_KEY="sk-fk-..."

Este é o primeiro ponto em que as equipes criam atrito evitável. Mantenha a chave no servidor, não no código do navegador e nem em uma nota local compartilhada. Se a avaliação for para uma equipe de produto e não para um único engenheiro, use desde o início um segredo de propriedade da equipe.

Etapa 2: execute o menor teste de fumaça possível do router

O quickstart atual da Flatkey usa POST /v1/chat/completions para a primeira solicitação. Essa é a abordagem certa mesmo que seu objetivo final seja a geração de vídeo com Seedance, porque ela verifica a camada de acesso compartilhada antes de você adicionar a complexidade de um fluxo assíncrono.

curl https://router.flatkey.ai/v1/chat/completions   -H "Authorization: Bearer $FLATKEY_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Responda com a palavra connected."}
    ]
  }'

Uma resposta bem-sucedida informa imediatamente cinco coisas úteis:

• a chave de API é válida
• o cabeçalho Authorization: Bearer ... está correto
• a URL base está correta
• seu cliente consegue fazer POST de JSON com sucesso
• a solicitação deve aparecer nos Flatkey Usage Logs com contagens de tokens e custo

Essa é a menor prova revisável de que a camada de acesso funciona.

Etapa 3: entenda o que a solicitação de teste de fumaça está realmente verificando

O teste de fumaça de chat completions é intencionalmente simples. A estrutura obrigatória é:

Campo da solicitação	Por que isso importa
cabeçalho Authorization	Confirma o formato do token Bearer
Content-Type: application/json	Confirma que o corpo da solicitação é interpretado corretamente
model	Confirma que a rota consegue resolver um ID de modelo
messages	Confirma que o corpo corresponde ao esquema compatível com a OpenAI

A documentação atual de chat-completions da Flatkey também destaca os três campos de resposta que as equipes de produto geralmente inspecionam primeiro:

• choices[0].message.content
• model
• usage

Esse último campo é especialmente útil para onboarding, porque oferece às equipes de produto e operações um ponto em comum para verificar que a solicitação realmente passou pelo router.

Etapa 4: substitua o modelo placeholder pela avaliação do Seedance

Depois que o teste de fumaça passar, mantenha a mesma credencial e a mesma URL base do router e então altere apenas as partes específicas do seu fluxo de trabalho de vídeo.

Mantenha inalterados estes itens:

• Authorization: Bearer $FLATKEY_API_KEY
• https://router.flatkey.ai/v1
• seu tratamento de segredo no lado do servidor
• seu caminho de revisão de logs e faturamento

Altere estes próximos:

O que muda após o teste de fumaça	Por que isso muda
model	Você substitui o texto placeholder do modelo pelo ID aprovado do modelo Seedance
Formato do corpo da solicitação	A geração de vídeo precisa de seus próprios campos de payload, não apenas de uma matriz messages de chat
Tratamento da resposta	Os fluxos de vídeo retornam estado do job, ativos ou status assíncrono em vez de apenas texto imediato
Lógica do produto	Você precisa de polling ou de um webhook em vez de tratar a chamada como chat síncrono

Para uma avaliação de produto de texto para vídeo, o placeholder seguro para o dia de publicação é:

seedance-2.5

Para uma avaliação de imagem para vídeo, a rota pública atual é:

seedance-2.0-i2v

Use esses nomes como ponto de partida para a descoberta, não como uma promessa de que todo fluxo downstream compartilha um único formato de payload idêntico.

Passo 5: projete em torno do fluxo assíncrono de vídeo do Seedance

Este é o passo que a maioria dos quickstarts pula.

A página pública da API do Seedance ainda descreve o fluxo como:

• criação assíncrona de tarefas
• polling de status
• webhooks
• créditos baseados em uso

Isso significa que uma equipe de produção deve assumir que o caminho real de vídeo precisa de pelo menos quatro estados no próprio app:

Estado do job	O que seu app deve fazer
queued	Registrar o job e mostrar que a solicitação foi aceita
running	Fazer polling do status ou aguardar um webhook
succeeded	Recuperar o ativo de saída e anexar metadados
failed	Salvar o erro e decidir se deve tentar novamente

Se sua equipe tentar tratar o Seedance como uma resposta síncrona de chat, a integração parecerá instável mesmo quando a API estiver se comportando normalmente.

Sequência prática de onboarding para equipes de produto

Se você quiser o ciclo de avaliação menor possível, use esta ordem:

1. Crie a chave Flatkey.
2. Execute o teste de fumaça chat/completions.
3. Verifique se a solicitação aparece em Usage Logs.
4. Escolha o ID do modelo Seedance atual que você realmente quer testar.
5. Implemente o fluxo de solicitação assíncrona específico do Seedance.
6. Adicione um caminho de polling ou um caminho de webhook antes de ampliar o rollout.

Isso reduz o risco de onboarding porque você separa a verificação do roteador da implementação do fluxo de vídeo.

Solucão de problemas

401 ou 403 na primeira solicitação cURL

Geralmente significa que a chave é inválida, expirou ou não está sendo passada como token Bearer.

Verifique:

• se a chave começa com sk-fk-
• se a variável do shell está realmente definida
• se o cabeçalho é Authorization: Bearer ...

404 ou incompatibilidade de rota

Geralmente significa que seu app está apontando para a URL errada.

Use:

https://router.flatkey.ai/v1

Não aponte a solicitação para o site de marketing nem remova o sufixo /v1.

A solicitação é bem-sucedida, mas os Usage Logs continuam vazios

O quickstart da Flatkey diz explicitamente para aguardar alguns segundos e pesquisar novamente. Se os logs ainda não aparecerem, verifique novamente o nome do modelo, a chave de API e a base URL que você realmente enviou.

O teste de fumaça funciona, mas o fluxo de trabalho do Seedance não

Isso normalmente significa que a camada de acesso está funcionando e que o problema agora está em um destes pontos:

• ID de modelo do Seedance incorreto
• formato incorreto do payload de vídeo
• lógica de polling assíncrona ausente
• manuseio de webhook ainda não implementado
• código do produto assumindo uma resposta de texto síncrona

Isso é progresso, não falha. Você já isolou o problema de autenticação e roteamento.

Quando este quickstart é suficiente

Este quickstart é suficiente quando sua equipe precisa responder:

• Conseguimos autenticar por meio da Flatkey?
• Conseguimos reutilizar nosso caminho de cliente compatível com OpenAI?
• Produto e operações conseguem ver a solicitação nos logs?
• Conseguimos mudar de um teste de fumaça em texto para uma rota Seedance sem adicionar primeiro outra chave de provedor?

Se a resposta para essas quatro perguntas for sim, a próxima etapa de aprovação normalmente é sobre o fluxo de trabalho assíncrono de vídeo e o modelo de custo, não sobre conectividade básica.

Se você precisar do lado de preços antes do lançamento, revise em seguida a página de preços ao vivo da Flatkey para que a equipe possa aprovar a avaliação com a mesma superfície de cobrança que será usada em produção.

FAQ

Qual é a maneira mais rápida de testar o acesso à API Seedance pela Flatkey?

Comece com o teste de fumaça atual da Flatkey em POST /v1/chat/completions para verificar autenticação, base URL e Usage Logs. Depois que isso funcionar, troque o modelo de placeholder pelo ID do modelo Seedance aprovado atualmente e construa o fluxo de trabalho assíncrono de vídeo.

A primeira solicitação cURL gera um vídeo?

Não. A primeira solicitação cURL é uma verificação de conectividade para o roteador compartilhado. Ela prova que sua chave, cabeçalhos, base URL e logs funcionam antes de você adicionar o tratamento de solicitações específico de vídeo.

Com qual modelo Seedance uma equipe de texto para vídeo deve começar?

Em sexta-feira, 17 de julho de 2026, o catálogo público de modelos da Flatkey lista seedance-2.5 para texto para vídeo e imagem para vídeo. Verifique novamente o diretório de modelos atual antes de fixá-lo no código do produto.

Com qual modelo Seedance uma equipe de imagem para vídeo deve começar?

Em sexta-feira, 17 de julho de 2026, o catálogo público da Flatkey lista seedance-2.0-i2v para imagem para vídeo.

Por que o fluxo de onboarding começa com chat completions em vez de um job de vídeo?

Porque a solicitação de chat completions é a prova mínima possível de que seu caminho de roteamento compatível com OpenAI funciona. Ela separa problemas de autenticação e logging dos problemas do pipeline de vídeo.

O que devo inspecionar na primeira resposta bem-sucedida?

Inspecione model, choices[0].message.content e usage, depois confirme que a mesma solicitação aparece em Usage Logs.

O que muda quando eu saio do teste de fumaça para uma avaliação real do Seedance?

A chave e a base URL permanecem as mesmas. O ID do modelo, o corpo da solicitação e o tratamento do job assíncrono mudam.