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 incluem seedance-2.0 e seedance-2.0-fast. 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. Use "seedance-2.0" ou "seedance-2.0-fast".

array

obrigatório

Itens de entrada multimodal. Inclua pelo menos um item de texto não vazio, URL de imagem ou URL de vídeo.

string

Resolução de saída: "480p", "720p" ou "1080p".

string

Proporção de saída: "16:9", "4:3", "1:1", "3:4", "9:16", "21:9" ou "adaptive".

integer

Duração do vídeo de 4 a 15 segundos. Use -1 para deixar o modelo escolher.

integer

Semente aleatória. Omita para usar uma semente aleatória.

boolean

Se deve adicionar uma marca d’água. Padrão: false.

boolean

Se deve gerar áudio sincronizado.

Itens de `content`

`type`	Campo de valor	`role` suportado	Finalidade
`text`	`text`	—	Prompt de texto. Múltiplos itens de texto são concatenados em ordem.
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`	Imagem de entrada ou referência. Até 9 imagens.
`video_url`	`video_url.url`	`reference_video`	Vídeo de referência. Até 3 vídeos.
`audio_url`	`audio_url.url`	`reference_audio`	Áudio de referência. Até 3 clipes.

Se uma imagem usar o papel first_frame ou last_frame, a API opera no modo de primeiro/último quadro. As demais imagens são tratadas como referências.

Parâmetros avançados

string

Modo de entrada explícito: "reference" ou "first_last_frame". Omita para inferir o modo a partir de content.

boolean

Ativa o aprimoramento por busca na web para a tarefa.

object

Aumenta a resolução do vídeo gerado mantendo o mesmo ID de tarefa público.

Mostrar Campos de super_resolution_config

string

Resolução alvo: "720p", "1080p", "2k" ou "4k". Deve ser maior que a resolução original e não pode ser combinado com resolution_limit.

integer

Limite de pixels personalizado para a dimensão menor, de 64 a 2160. Não pode ser combinado com resolution.

string

Cena de upscaling: "aigc", "short_series", "ugc" ou "old_film".

string

Modo de upscaling: "standard" (padrão) ou "professional".

integer

Taxa de quadros de saída de 1 a 120. Valores acima da taxa de quadros da fonte ativam a interpolação de quadros.

camera_fixed, frames, callback_url e return_last_frame são aceitos por compatibilidade, mas atualmente não têm efeito.

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
}

Referência multimodal com upscaling

{
  "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,
  "super_resolution_config": {
    "resolution": "4k",
    "scene": "aigc",
    "tool_version": "professional",
    "fps": 60
  }
}

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"
  },
  "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": "video_generation_failed"
  }
}

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.

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. 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.
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`

Parâmetros avançados

Exemplos de requisição

Entrada com primeiro e último quadro

Referência multimodal com upscaling

Resposta

Campos da resposta

Consultar status da tarefa

Valores de status

Baixar o vídeo

Erros

Exemplo completo

​Endpoint

​Requisição

​Cabeçalhos

​Parâmetros do corpo

​Itens de content

​Parâmetros avançados

​Exemplos de requisição

​Entrada com primeiro e último quadro

​Referência multimodal com upscaling

​Resposta

​Campos da resposta

​Consultar status da tarefa

​Valores de status

​Baixar o vídeo

​Erros

​Exemplo completo

Endpoint

Requisição

Cabeçalhos

Parâmetros do corpo

Itens de `content`

Parâmetros avançados

Exemplos de requisição

Entrada com primeiro e último quadro

Referência multimodal com upscaling

Resposta

Campos da resposta

Consultar status da tarefa

Valores de status

Baixar o vídeo

Erros

Exemplo completo