Geração de Vídeo Seedance — POST /v1/videos

Use POST /v1/videos para criar uma tarefa assíncrona de geração de vídeo Seedance. Consulte o status da tarefa até que ela seja concluída e, em seguida, baixe o vídeo pela URL do Flatkey retornada. Os modelos suportados são seedance-2.0, seedance-2.0-fast, seedance-2.0-mini e seedance-2.5. A disponibilidade depende da sua conta; use GET /v1/models para obter a lista atual de modelos.

Endpoint

POST https://router.flatkey.ai/v1/videos

O Flatkey também aceita POST /v1/video/generations e GET /v1/video/generations/{task_id}. Use /v1/videos para a estrutura de resposta padrão e dados nativos de usage.

Requisição

Cabeçalhos

Cabeçalho	Valor
`Authorization`	`Bearer $FLATKEY_API_KEY`
`Content-Type`	`application/json`

Parâmetros do corpo

string

obrigatório

ID do modelo Seedance: "seedance-2.0", "seedance-2.0-fast", "seedance-2.0-mini" ou "seedance-2.5".

array

obrigatório

Itens de entrada multimodal. Inclua pelo menos um item de texto não vazio, imagem, vídeo ou áudio. Veja itens de content.

string

Resolução de saída. Padrão: "720p".

Modelo	Valores suportados
`seedance-2.0`	`"480p"`, `"720p"`, `"1080p"`, `"4k"`
`seedance-2.0-fast`, `seedance-2.0-mini`	`"480p"`, `"720p"`
`seedance-2.5`	`"480p"`, `"720p"`, `"1080p"`

string

Proporção de saída: "16:9", "4:3", "1:1", "3:4", "9:16", "21:9" ou "adaptive". Padrão: "adaptive". Com "adaptive", o modelo escolhe a proporção com base nas imagens ou vídeos de entrada. Para seedance-2.5, tarefas de primeiro quadro e de primeiro/último quadro aceitam apenas "adaptive".

integer

Duração do vídeo em segundos. Padrão: 5. Os modelos Seedance 2.0 aceitam de 4 a 15; o seedance-2.5 aceita de 4 a 30.

Sempre envie um duration positivo. O Flatkey cobra o Seedance por segundo, então -1 (deixar o modelo escolher a duração) é rejeitado com video_price_not_configured. A única exceção é uma edição de vídeo do seedance-2.5, que exige -1.

boolean

Adiciona uma marca d’água “AI generated” no canto inferior direito. Padrão: false.

boolean

Gera uma faixa de áudio mono sincronizada. Padrão: true. Defina como false se você precisar apenas do vídeo; o áudio gerado pode ocasionalmente ser reprovado em verificações de direitos autorais.

boolean

Retorna o último quadro do vídeo gerado como imagem. Padrão: false. Quando true, a tarefa concluída inclui metadata.last_frame_url, que baixa um JPEG com as mesmas dimensões do vídeo e sem marca d’água. Use-o como first_frame da próxima tarefa para encadear clipes. Assim como metadata.url, ele não requer cabeçalho de autorização; trate-o como privado.

string

Somente seedance-2.5. Contêiner do vídeo gerado: "mp4" ou "mov". Padrão: "mp4". O MOV preserva mais precisão de cor para correção de cor e composição (H.264, YUV 4:4:4, áudio PCM), mas alguns players não conseguem abri-lo. O endpoint de conteúdo retorna video/quicktime para resultados em MOV.

string

Somente seedance-2.5, para tarefas no modo de referência. Informa ao modelo qual tarefa você pretende realizar: "auto" (padrão), "reference", "edit" ou "extend". Defini-lo explicitamente antecipa as verificações de tipo de tarefa para o momento do envio, de modo que uma combinação inválida falha imediatamente, e não depois que a tarefa começa. "reference", "edit" e "extend" exigem itens de referência em content; uma requisição só com texto e "reference" é rejeitada. Veja edição e extensão de vídeo.

integer

Prioridade na fila, de 0 a 9. Padrão: 0. Valores mais altos colocam a tarefa à frente de tarefas de menor prioridade que aguardam o mesmo modelo. Compatível com todos os modelos Seedance 2.0 e com o seedance-2.5. Valores fora do intervalo 0–9 são rejeitados com 400.

integer

Segundos que a tarefa pode aguardar e ser executada antes de expirar. Padrão: 172800 (48 horas). Use um valor menor quando um resultado atrasado não tiver utilidade para você.

string

URL HTTPS pública que recebe um POST sempre que o status da tarefa muda. Veja Callbacks de tarefa. Deve usar https, não conter credenciais de usuário, ter no máximo 2.048 caracteres e resolver para um endereço público; caso contrário, a requisição é rejeitada com 400.

Itens de `content`

`type`	Campo de valor	`role` suportado	Limites
`text`	`text`	—	Texto do prompt. Mantenha-o abaixo de cerca de 1.000 palavras em inglês.
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`	Até 9 imagens de referência (`seedance-2.5`: 30). JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC ou HEIF; menos de 30 MB; 300–6000 px por lado; proporção entre 0,4 e 2,5.
`video_url`	`video_url.url`	`reference_video`	Até 3 vídeos, de 2 a 15 segundos cada e 15 segundos no total (`seedance-2.5`: 10 vídeos, 30 segundos). MP4 ou MOV; menos de 200 MB; pelo menos cerca de 409.600 pixels no total (por exemplo, 854×480).
`audio_url`	`audio_url.url`	`reference_audio`	Até 3 clipes, de 2 a 15 segundos cada e 15 segundos no total (`seedance-2.5`: 10 clipes, 30 segundos). WAV ou MP3; menos de 15 MB. Os modelos Seedance 2.0 precisam de pelo menos uma imagem ou um vídeo junto com o áudio.

Cada URL pode ser uma URL HTTPS pública, uma data URI data:<mime>;base64, (somente imagens e áudio) ou uma referência asset:// da biblioteca de ativos. O corpo inteiro da requisição deve ficar abaixo de 64 MB. Escolha um modo de entrada por tarefa. Estes modos não podem ser combinados:

Modo	Como montar o `content`
Primeiro quadro	Uma imagem com `role: "first_frame"`.
Primeiro e último quadros	Duas imagens, uma com `role: "first_frame"` e outra com `role: "last_frame"`. `last_frame` sempre exige um `first_frame`, e nenhum dos dois pode ser combinado com itens de referência.
Referência	Qualquer combinação de itens `reference_image`, `reference_video` e `reference_audio`.

Edição de vídeo

O seedance-2.5 pode editar ou estender um vídeo existente no modo de referência. Descreva a alteração no prompt e refira-se ao vídeo como @Video1.

Tarefa	Configurações obrigatórias	Duração da saída
Edição (substituir um sujeito, adicionar ou remover objetos, alterar o áudio)	Pelo menos um `reference_video` com 4–30 segundos, `ratio: "adaptive"`, `duration: -1`. Recomendado: `omni_reference_task_type: "edit"`.	Igual à do vídeo de entrada editado
Extensão (continuar um vídeo para a frente ou para trás)	Pelo menos um `reference_video`, `ratio: "adaptive"`, um `duration` positivo. Recomendado: `omni_reference_task_type: "extend"`.	`duration`

{
  "model": "seedance-2.5",
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": -1,
  "omni_reference_task_type": "edit",
  "content": [
    { "type": "text", "text": "Edit @Video1: make the ball bright green and keep everything else unchanged." },
    { "type": "video_url", "video_url": { "url": "https://example.com/input.mp4" }, "role": "reference_video" }
  ]
}

Como toda requisição do seedance-2.5 com vídeo de referência, uma edição é cobrada pela tarifa com vídeo da resolução escolhida, por 30 segundos fixos, independentemente da duração da entrada ou da saída.

Modo rascunho

O seedance-2.5 pode gerar primeiro um rascunho barato em 480p, para que você confira a cena, os planos e o movimento antes de pagar pelo vídeo final. São necessárias duas requisições:

Crie o rascunho. Envie uma requisição normal com "draft": true e "resolution": "480p". Ela é cobrada como um vídeo 480p comum.
Gere o vídeo final. Depois que o rascunho for concluído, envie uma requisição cujo único item de content seja um draft_task apontando para o ID da tarefa do rascunho, com "resolution": "1080p".

{
  "model": "seedance-2.5",
  "resolution": "1080p",
  "content": [
    { "type": "draft_task", "draft_task": { "id": "task_3f9a00000000000000000000000000e2" } }
  ]
}

O vídeo final reaproveita o prompt, as mídias, a duração, a proporção, a semente, a configuração de áudio e o tipo de tarefa do rascunho. Não envie duration, ratio, frames, seed, generate_audio, omni_reference_task_type, draft nem qualquer outro item de content junto com um draft_task; a requisição é rejeitada com 400. Você ainda pode definir return_last_frame, output_format, watermark, priority, execution_expires_after e callback_url.

Regra	Detalhe
Modelo	`model` deve ser igual ao do rascunho.
ID da tarefa do rascunho	Use o ID `task_…` que o Flatkey retornou para o rascunho. A tarefa deve ser sua e precisa estar concluída.
Resolução	Rascunho: somente `480p`. Vídeo final: somente `1080p`.
Validade	Um rascunho pode ser usado por 7 dias após a criação.
Cobrança	O vídeo final é cobrado pela tarifa de 1080p, pela duração do rascunho. Se o rascunho usou um vídeo de referência, aplica-se a tarifa com vídeo por 30 segundos fixos.

O Seedance não aceita diretamente imagens ou vídeos que mostrem rostos humanos reais. Envie-os como ativos de pessoa real e referencie-os com asset://.

Exemplos de requisição

import os
import requests

response = requests.post(
    "https://router.flatkey.ai/v1/videos",
    headers={
        "Authorization": f"Bearer {os.environ['FLATKEY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "seedance-2.0",
        "content": [
            {
                "type": "text",
                "text": "An astronaut walking on the moon, cinematic lighting, slow camera push-in",
            }
        ],
        "resolution": "1080p",
        "ratio": "16:9",
        "duration": 5,
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://router.flatkey.ai/v1/videos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FLATKEY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2.0",
    content: [
      {
        type: "text",
        text: "An astronaut walking on the moon, cinematic lighting, slow camera push-in",
      },
    ],
    resolution: "1080p",
    ratio: "16:9",
    duration: 5,
  }),
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

curl https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "An astronaut walking on the moon, cinematic lighting, slow camera push-in"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

Entrada com primeiro e último quadro

{
  "model": "seedance-2.0",
  "content": [
    { "type": "text", "text": "The camera slowly moves forward" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first.jpg" },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/last.jpg" },
      "role": "last_frame"
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": false
}

Referência multimodal

{
  "model": "seedance-2.0",
  "content": [
    { "type": "text", "text": "A woman smiles at the camera during a beach sunset" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/reference.jpg" },
      "role": "reference_image"
    }
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5,
  "watermark": false
}

Resposta

{
  "id": "task_3f9a00000000000000000000000000e2",
  "task_id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "model": "seedance-2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1780306574
}

Campos da resposta

string

ID público da tarefa usado para consultar o status e baixar o vídeo concluído. task_id contém o mesmo valor.

string

Status da tarefa: queued, in_progress, completed ou failed.

integer

Progresso da geração de 0 a 100.

integer

Timestamp Unix da criação da tarefa.

Consultar status da tarefa

GET https://router.flatkey.ai/v1/videos/{task_id}

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

Enquanto a geração está em andamento, a resposta inclui o progresso atual:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "in_progress",
  "progress": 50,
  "model": "seedance-2.0",
  "created_at": 1780306574
}

Quando a tarefa é concluída, a resposta inclui a URL do vídeo e o uso de tokens:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "model": "seedance-2.0",
  "usage": {
    "completion_tokens": 120,
    "total_tokens": 120
  },
  "metadata": {
    "url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content",
    "last_frame_url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/last-frame"
  },
  "created_at": 1780306574,
  "completed_at": 1780306750
}

Tarefas com falha retornam os detalhes do erro junto com a resposta da tarefa:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "failed",
  "error": {
    "message": "The video generation task failed.",
    "code": ""
  }
}

Qualquer saldo pré-consumido é reembolsado automaticamente.

Valores de status

Status	Significado
`queued`	A tarefa está aguardando para iniciar.
`in_progress`	O vídeo está sendo gerado. `progress` varia de 0 a 100.
`completed`	O vídeo está disponível em `metadata.url` e o uso de tokens está disponível em `usage`.
`failed`	A geração falhou. Os detalhes estão disponíveis em `error.message` e qualquer saldo pré-consumido é reembolsado.

Callbacks de tarefa

Defina callback_url para receber as mudanças de status em vez de consultar a tarefa periodicamente, ou além disso. O Flatkey envia um POST com Content-Type: application/json quando a tarefa passa para in_progress, completed ou failed. O corpo é exatamente o que GET /v1/videos/{task_id} retorna naquele momento, incluindo metadata.url e metadata.last_frame_url para tarefas concluídas.

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "model": "seedance-2.0",
  "usage": {
    "completion_tokens": 120,
    "total_tokens": 120
  },
  "metadata": {
    "url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content"
  },
  "created_at": 1780306574,
  "completed_at": 1780306750
}

Cabeçalho	Valor
`X-Flatkey-Event-Id`	`<task_id>:<status>`, por exemplo `task_3f9a…e2:completed`. O mesmo evento pode ser entregue mais de uma vez; use este cabeçalho para ignorar duplicatas.

Responda com qualquer status 2xx em até 5 segundos. Caso contrário, o Flatkey tenta novamente duas vezes, após 2 e 8 segundos, e então desiste. Redirecionamentos não são seguidos. Os callbacks não são assinados; por isso, confirme o resultado consultando a tarefa antes de agir com base nele e mantenha a consulta como fonte da verdade caso um callback se perca.

Baixar o vídeo

GET https://router.flatkey.ai/v1/videos/{task_id}/content

curl -L "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content" \
  -o output.mp4

O endpoint de conteúdo transmite dados video/mp4, ou video/quicktime quando a tarefa usou output_format: "mov". Não requer um token Bearer e pode ser usado diretamente como fonte de um elemento <video>.

O endpoint de conteúdo funciona apenas após a conclusão da tarefa e tem limite de taxa por IP do cliente. Trate a URL como informação sensível, pois qualquer pessoa que a possua pode baixar o vídeo.

Erros

Erros em tempo de requisição usam o envelope de erro padrão do Flatkey:

{
  "error": {
    "message": "...",
    "type": "...",
    "code": "..."
  }
}

Cenário	Comportamento
`content` vazio	A requisição é rejeitada. Inclua texto não vazio, uma imagem ou um vídeo.
Modelo indisponível	O `model` solicitado não está habilitado para a rota.
Saldo insuficiente	A tarefa não é criada.
`priority` fora de 0–9	A requisição retorna `400` com `invalid_request`.
`callback_url` inválido	A requisição retorna `400` com `invalid_request` quando a URL não é HTTPS, contém credenciais, tem mais de 2.048 caracteres ou aponta para um endereço privado ou local.
`duration: -1` fora de uma edição de vídeo do `seedance-2.5`	A requisição retorna `400` com `video_price_not_configured`.
Entrada inválida para o modelo	A requisição retorna `400` com `fail_to_fetch_task` ou, em requisições que usam referências `asset://`, a tarefa falha com `task preparation failed`. Verifique a resolução, a duração, os limites de conteúdo e as regras de modo de entrada acima. Nada é cobrado.
Falha temporária no serviço	Tente novamente mais tarde usando sua política de backoff habitual.

Exemplo completo

Este exemplo cria uma tarefa, consulta o status a cada cinco segundos e baixa o vídeo concluído. Requer jq.

#!/usr/bin/env bash
set -euo pipefail

BASE="https://router.flatkey.ai"
: "${FLATKEY_API_KEY:?Set FLATKEY_API_KEY before running this script}"

RESPONSE=$(curl -sS "$BASE/v1/videos" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      { "type": "text", "text": "An astronaut walking on the moon, cinematic lighting" }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }')

TASK_ID=$(echo "$RESPONSE" | jq -r '.id')
echo "task: $TASK_ID"

while true; do
  RESULT=$(curl -sS "$BASE/v1/videos/$TASK_ID" \
    -H "Authorization: Bearer $FLATKEY_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  echo "status: $STATUS"

  [ "$STATUS" = "completed" ] && break
  if [ "$STATUS" = "failed" ]; then
    echo "failed: $(echo "$RESULT" | jq -r '.error.message')" >&2
    exit 1
  fi
  sleep 5
done

VIDEO_URL=$(echo "$RESULT" | jq -r '.metadata.url')
curl -L "$VIDEO_URL" -o output.mp4
echo "saved -> output.mp4"

Visão geral

Endpoints

Geração de Vídeo Seedance — POST /v1/videos

Endpoint

Requisição

Cabeçalhos

Parâmetros do corpo

Itens de `content`

Edição de vídeo

Modo rascunho

Exemplos de requisição

Entrada com primeiro e último quadro

Referência multimodal

Resposta

Campos da resposta

Consultar status da tarefa

Valores de status

Callbacks de tarefa

Baixar o vídeo

Erros

Exemplo completo

​Endpoint

​Requisição

​Cabeçalhos

​Parâmetros do corpo

​Itens de content

​Edição de vídeo

​Modo rascunho

​Exemplos de requisição

​Entrada com primeiro e último quadro

​Referência multimodal

​Resposta

​Campos da resposta

​Consultar status da tarefa

​Valores de status

​Callbacks de tarefa

​Baixar o vídeo

​Erros

​Exemplo completo

Endpoint

Requisição

Cabeçalhos

Parâmetros do corpo

Itens de `content`

Edição de vídeo

Modo rascunho

Exemplos de requisição

Entrada com primeiro e último quadro

Referência multimodal

Resposta

Campos da resposta

Consultar status da tarefa

Valores de status

Callbacks de tarefa

Baixar o vídeo

Erros

Exemplo completo