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 son seedance-2.0, seedance-2.0-fast, seedance-2.0-mini y seedance-2.5. 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: "seedance-2.0", "seedance-2.0-fast", "seedance-2.0-mini" o "seedance-2.5".

array

requerido

Elementos de entrada multimodal. Incluye al menos un elemento no vacío de texto, imagen, vídeo o audio. Consulta Elementos de content.

string

Resolución de salida. Valor por defecto: "720p".

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

string

Relación de aspecto de salida: "16:9", "4:3", "1:1", "3:4", "9:16", "21:9" o "adaptive". Valor por defecto: "adaptive". Con "adaptive", el modelo elige la relación de aspecto a partir de tus imágenes o vídeos de entrada. En seedance-2.5, las tareas de primer fotograma y de primer y último fotograma solo admiten "adaptive".

integer

Duración del vídeo en segundos. Valor por defecto: 5. Los modelos Seedance 2.0 admiten de 4 a 15; seedance-2.5 admite de 4 a 30.

Envía siempre un valor positivo en duration. Flatkey factura Seedance por segundo, por lo que -1 (dejar que el modelo elija la duración) se rechaza con video_price_not_configured. La única excepción es una edición de vídeo con seedance-2.5, que requiere -1.

boolean

Añade una marca de agua “AI generated” en la esquina inferior derecha. Valor por defecto: false.

boolean

Genera una pista de audio mono sincronizada. Valor por defecto: true. Establécelo en false si solo necesitas el vídeo; el audio generado puede no superar ocasionalmente las comprobaciones de derechos de autor.

boolean

Devuelve el último fotograma del vídeo generado como imagen. Valor por defecto: false. Si es true, la tarea completada incluye metadata.last_frame_url, que descarga un JPEG con las mismas dimensiones que el vídeo y sin marca de agua. Úsalo como first_frame de la siguiente tarea para encadenar clips. Al igual que metadata.url, no requiere cabecera de autorización; trátalo como privado.

string

Solo seedance-2.5. Contenedor del vídeo generado: "mp4" o "mov". Valor por defecto: "mp4". MOV conserva más precisión de color para etalonaje y composición (H.264, YUV 4:4:4, audio PCM), pero algunos reproductores no pueden abrirlo. El endpoint de contenido devuelve video/quicktime para los resultados en MOV.

string

Solo seedance-2.5, para tareas en modo de referencia. Indica al modelo qué tarea quieres realizar: "auto" (valor por defecto), "reference", "edit" o "extend". Si lo estableces explícitamente, las comprobaciones del tipo de tarea se hacen en el envío, de modo que una combinación no válida falla de inmediato en lugar de después de que empiece la tarea. "reference", "edit" y "extend" necesitan elementos de referencia en content; una solicitud solo de texto con "reference" se rechaza. Consulta edición y extensión de vídeo.

integer

Prioridad en la cola, de 0 a 9. Valor por defecto: 0. Los valores más altos adelantan la tarea a las tareas de menor prioridad que esperan en el mismo modelo. Compatible con todos los modelos Seedance 2.0 y con seedance-2.5. Los valores fuera del rango de 0 a 9 se rechazan con 400.

integer

Segundos que la tarea puede esperar y ejecutarse antes de caducar. Valor por defecto: 172800 (48 horas). Usa un valor menor si un resultado tardío no te sirve.

string

URL HTTPS pública que recibe un POST cada vez que cambia el estado de la tarea. Consulta Callbacks de tareas. Debe usar https, no contener credenciales de usuario, tener como máximo 2.048 caracteres y resolverse a una dirección pública; de lo contrario, la solicitud se rechaza con 400.

Elementos de `content`

`type`	Campo de valor	`role` admitido	Límites
`text`	`text`	—	Texto del prompt. Mantenlo por debajo de unas 1.000 palabras en inglés.
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`	Hasta 9 imágenes de referencia (`seedance-2.5`: 30). JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC o HEIF; menos de 30 MB; de 300 a 6000 px por lado; relación de aspecto de 0,4 a 2,5.
`video_url`	`video_url.url`	`reference_video`	Hasta 3 vídeos, de 2 a 15 segundos cada uno y 15 segundos en total (`seedance-2.5`: 10 vídeos, 30 segundos). MP4 o MOV; menos de 200 MB; al menos unos 409.600 píxeles en total (por ejemplo, 854×480).
`audio_url`	`audio_url.url`	`reference_audio`	Hasta 3 clips, de 2 a 15 segundos cada uno y 15 segundos en total (`seedance-2.5`: 10 clips, 30 segundos). WAV o MP3; menos de 15 MB. Los modelos Seedance 2.0 necesitan al menos una imagen o un vídeo junto con el audio.

Cada URL puede ser una URL HTTPS pública, un data URI data:<mime>;base64, (solo imágenes y audio) o una referencia asset:// de la biblioteca de activos. El cuerpo completo de la solicitud debe ocupar menos de 64 MB. Elige un único modo de entrada por tarea. Estos modos no se pueden mezclar:

Modo	Cómo construir `content`
Primer fotograma	Una imagen con `role: "first_frame"`.
Primer y último fotograma	Dos imágenes, una con `role: "first_frame"` y otra con `role: "last_frame"`. `last_frame` siempre necesita un `first_frame`, y ninguno de los dos puede combinarse con elementos de referencia.
Referencia	Cualquier combinación de elementos `reference_image`, `reference_video` y `reference_audio`.

Edición de vídeo

seedance-2.5 puede editar o extender un vídeo existente en modo de referencia. Describe el cambio en el prompt y refiérete al vídeo como @Video1.

Tarea	Ajustes obligatorios	Duración de salida
Edición (reemplazar un sujeto, añadir o quitar objetos, cambiar el audio)	Al menos un `reference_video` de 4 a 30 segundos, `ratio: "adaptive"`, `duration: -1`. Recomendado: `omni_reference_task_type: "edit"`.	La misma que la del vídeo de entrada editado
Extensión (continuar un vídeo hacia delante o hacia atrás)	Al menos un `reference_video`, `ratio: "adaptive"`, un valor positivo en `duration`. 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" }
  ]
}

Al igual que cualquier solicitud de seedance-2.5 con un vídeo de referencia, una edición se factura con la tarifa con vídeo de la resolución correspondiente por 30 segundos fijos, independientemente de la duración de entrada o de salida.

Modo borrador

seedance-2.5 puede generar primero un borrador económico en 480p para que compruebes la escena, los planos y el movimiento antes de pagar por el vídeo final. Se necesitan dos solicitudes:

Crea el borrador. Envía una solicitud normal con "draft": true y "resolution": "480p". Se factura como un vídeo estándar de 480p.
Genera el vídeo final. Cuando el borrador se complete, envía una solicitud cuyo único elemento de content sea un draft_task que apunte al ID de la tarea del borrador, con "resolution": "1080p".

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

El vídeo final reutiliza el prompt, los archivos multimedia, la duración, la relación de aspecto, la semilla, el ajuste de audio y el tipo de tarea del borrador. No envíes duration, ratio, frames, seed, generate_audio, omni_reference_task_type, draft ni ningún otro elemento de content junto con un draft_task; la solicitud se rechaza con 400. Puedes seguir configurando return_last_frame, output_format, watermark, priority, execution_expires_after y callback_url.

Regla	Detalle
Modelo	`model` debe coincidir con el del borrador.
ID de la tarea del borrador	Usa el ID `task_…` que Flatkey devolvió para el borrador. Debe ser una tarea tuya y debe haberse completado.
Resolución	Borrador: solo `480p`. Vídeo final: solo `1080p`.
Caducidad	Un borrador se puede usar durante 7 días desde su creación.
Facturación	El vídeo final se factura con la tarifa de 1080p por la duración del borrador. Si el borrador usó un vídeo de referencia, se aplica la tarifa con vídeo por 30 segundos fijos.

Seedance no acepta directamente imágenes ni vídeos que muestren rostros humanos reales. Súbelos como activos de persona real y haz referencia a ellos con asset://.

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

Referencia 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
}

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",
    "last_frame_url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/last-frame"
  },
  "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": ""
  }
}

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.

Callbacks de tareas

Configura callback_url para recibir los cambios de estado en lugar de consultar la tarea, o además de hacerlo. Flatkey envía un POST con Content-Type: application/json cuando la tarea pasa a in_progress, completed o failed. El cuerpo es exactamente lo que devuelve GET /v1/videos/{task_id} en ese momento, incluidos metadata.url y metadata.last_frame_url para las tareas completadas.

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

Cabecera	Valor
`X-Flatkey-Event-Id`	`<task_id>:<status>`, por ejemplo `task_3f9a…e2:completed`. El mismo evento puede entregarse más de una vez; usa esta cabecera para ignorar los duplicados.

Responde con cualquier estado 2xx en un plazo de 5 segundos. De lo contrario, Flatkey reintenta dos veces, a los 2 y a los 8 segundos, y después desiste. No se siguen las redirecciones. Los callbacks no están firmados, así que verifica el resultado consultando la tarea antes de actuar en consecuencia, y sigue usando la consulta como fuente de verdad por si se pierde algún callback.

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, o video/quicktime si la tarea usó output_format: "mov". 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.
`priority` fuera del rango de 0 a 9	La solicitud devuelve `400` con `invalid_request`.
`callback_url` no válida	La solicitud devuelve `400` con `invalid_request` cuando la URL no es HTTPS, contiene credenciales, supera los 2.048 caracteres o apunta a una dirección privada o local.
`duration: -1` fuera de una edición de vídeo con `seedance-2.5`	La solicitud devuelve `400` con `video_price_not_configured`.
Entrada no válida para el modelo	La solicitud devuelve `400` con `fail_to_fetch_task` o, en las solicitudes que usan referencias `asset://`, la tarea falla con `task preparation failed`. Revisa la resolución, la duración, los límites de contenido y las reglas de modo de entrada indicados arriba. No se te cobra nada.
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`

Edición de vídeo

Modo borrador

Ejemplos de solicitudes

Entrada con primer y último fotograma

Referencia multimodal

Respuesta

Campos de la respuesta

Consultar el estado de la tarea

Valores de estado

Callbacks de tareas

Descargar el vídeo

Errores

Ejemplo de extremo a extremo

​Endpoint

​Solicitud

​Cabeceras

​Parámetros del cuerpo

​Elementos de content

​Edición de vídeo

​Modo borrador

​Ejemplos de solicitudes

​Entrada con primer y último fotograma

​Referencia multimodal

​Respuesta

​Campos de la respuesta

​Consultar el estado de la tarea

​Valores de estado

​Callbacks de tareas

​Descargar el vídeo

​Errores

​Ejemplo de extremo a extremo

Endpoint

Solicitud

Cabeceras

Parámetros del cuerpo

Elementos de `content`

Edición de vídeo

Modo borrador

Ejemplos de solicitudes

Entrada con primer y último fotograma

Referencia multimodal

Respuesta

Campos de la respuesta

Consultar el estado de la tarea

Valores de estado

Callbacks de tareas

Descargar el vídeo

Errores

Ejemplo de extremo a extremo