Generación de vídeo Seedance — POST /v1/videos

Usa POST /v1/videos para crear una tarea asíncrona de generación de vídeo con Seedance. Consulta el estado de la tarea hasta que se complete y luego descarga el vídeo desde la URL de Flatkey devuelta. Los modelos compatibles incluyen seedance-2.0 y seedance-2.0-fast. La disponibilidad depende de tu cuenta; usa GET /v1/models para obtener la lista de modelos actual.

Endpoint

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

Flatkey también acepta POST /v1/video/generations y GET /v1/video/generations/{task_id}. Usa /v1/videos para obtener la estructura de respuesta estándar y los datos nativos de usage.

Solicitud

Cabeceras

Cabecera	Valor
`Authorization`	`Bearer $FLATKEY_API_KEY`
`Content-Type`	`application/json`

Parámetros del cuerpo

string

requerido

ID del modelo Seedance. Usa "seedance-2.0" o "seedance-2.0-fast".

array

requerido

Elementos de entrada multimodal. Incluye al menos un elemento de texto no vacío, una URL de imagen o una URL de vídeo.

string

Resolución de salida: "480p", "720p" o "1080p".

string

Relación de aspecto de salida: "16:9", "4:3", "1:1", "3:4", "9:16", "21:9" o "adaptive".

integer

Duración del vídeo de 4 a 15 segundos. Usa -1 para que el modelo elija.

integer

Semilla aleatoria. Omítela para usar una semilla aleatoria.

boolean

Si se añade una marca de agua. Valor por defecto: false.

boolean

Si se genera audio sincronizado.

Elementos de `content`

`type`	Campo de valor	`role` admitido	Finalidad
`text`	`text`	—	Indicación de texto. Varios elementos de texto se unen en orden.
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`	Imagen de entrada o referencia. Hasta 9 imágenes.
`video_url`	`video_url.url`	`reference_video`	Vídeo de referencia. Hasta 3 vídeos.
`audio_url`	`audio_url.url`	`reference_audio`	Audio de referencia. Hasta 3 clips.

Si una imagen usa el rol first_frame o last_frame, la API activa el modo de primer/último fotograma. Las demás imágenes se tratan como referencias.

Parámetros avanzados

string

Modo de entrada explícito: "reference" o "first_last_frame". Omítelo para inferir el modo a partir de content.

boolean

Activa la búsqueda web como complemento para la tarea.

object

Aumenta la resolución del vídeo generado manteniendo el mismo ID de tarea público.

Mostrar Campos de super_resolution_config

string

Resolución de destino: "720p", "1080p", "2k" o "4k". Debe superar la resolución original y no puede combinarse con resolution_limit.

integer

Límite personalizado de píxeles en el lado corto, de 64 a 2160. No puede combinarse con resolution.

string

Escena de escalado: "aigc", "short_series", "ugc" o "old_film".

string

Modo de escalado: "standard" (por defecto) o "professional".

integer

Tasa de fotogramas de salida de 1 a 120. Los valores superiores a la tasa de fotogramas original activan la interpolación de fotogramas.

camera_fixed, frames, callback_url y return_last_frame se aceptan por compatibilidad, pero actualmente no tienen ningún efecto.

Ejemplos de solicitudes

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 con primer y último fotograma

{
  "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
}

Referencia multimodal con escalado de resolución

{
  "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
  }
}

Respuesta

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

Campos de la respuesta

string

ID público de la tarea, que se usa para consultar su estado y descargar el vídeo completado. task_id contiene el mismo valor.

string

Estado de la tarea: queued, in_progress, completed o failed.

integer

Progreso de la generación de 0 a 100.

integer

Marca de tiempo Unix de la creación de la tarea.

Consultar el estado de la tarea

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

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

Mientras la generación está en curso, la respuesta incluye el progreso actual:

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

Cuando la tarea se completa, la respuesta incluye la URL del vídeo y el 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
}

Las tareas fallidas devuelven los detalles del error junto con la respuesta de la tarea:

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

Cualquier saldo consumido previamente se reembolsa de forma automática.

Valores de estado

Estado	Significado
`queued`	La tarea está en espera de inicio.
`in_progress`	El vídeo se está generando. `progress` varía de 0 a 100.
`completed`	El vídeo está disponible en `metadata.url` y el uso de tokens está disponible en `usage`.
`failed`	La generación ha fallado. Los detalles están disponibles en `error.message` y se reembolsa cualquier saldo consumido previamente.

Descargar el 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

El endpoint de contenido transmite datos video/mp4. No requiere token Bearer y puede usarse directamente como fuente de un elemento <video>.

El endpoint de contenido solo funciona una vez que la tarea se ha completado y tiene limitación de velocidad por IP de cliente. Trata la URL como información sensible, ya que cualquier persona que la tenga puede descargar el vídeo.

Errores

Los errores en el momento de la solicitud usan el sobre de error estándar de Flatkey:

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

Escenario	Comportamiento
`content` vacío	La solicitud es rechazada. Incluye texto no vacío, una imagen o un vídeo.
Modelo no disponible	El `model` solicitado no está habilitado para la ruta.
Saldo insuficiente	La tarea no se crea.
Fallo temporal del servicio	Reintenta más tarde usando tu política de retroceso habitual.

Ejemplo de extremo a extremo

Este ejemplo crea una tarea, consulta su estado cada cinco segundos y descarga el vídeo completado. Requiere 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"

Descripción general

Endpoints

Generación de vídeo Seedance — POST /v1/videos

Endpoint

Solicitud

Cabeceras

Parámetros del cuerpo

Elementos de `content`

Parámetros avanzados

Ejemplos de solicitudes

Entrada con primer y último fotograma

Referencia multimodal con escalado de resolución

Respuesta

Campos de la respuesta

Consultar el estado de la tarea

Valores de estado

Descargar el vídeo

Errores

Ejemplo de extremo a extremo

​Endpoint

​Solicitud

​Cabeceras

​Parámetros del cuerpo

​Elementos de content

​Parámetros avanzados

​Ejemplos de solicitudes

​Entrada con primer y último fotograma

​Referencia multimodal con escalado de resolución

​Respuesta

​Campos de la respuesta

​Consultar el estado de la tarea

​Valores de estado

​Descargar el vídeo

​Errores

​Ejemplo de extremo a extremo

Endpoint

Solicitud

Cabeceras

Parámetros del cuerpo

Elementos de `content`

Parámetros avanzados

Ejemplos de solicitudes

Entrada con primer y último fotograma

Referencia multimodal con escalado de resolución

Respuesta

Campos de la respuesta

Consultar el estado de la tarea

Valores de estado

Descargar el vídeo

Errores

Ejemplo de extremo a extremo