Genera vídeos de Seedance con Flatkey

URL base: https://router.flatkey.ai Esta guía te ofrece una ruta lista para copiar y usar Seedance a través de Flatkey. Empieza con una tarea de texto a vídeo, consulta la tarea hasta que se complete y luego descarga el MP4 generado. Si necesitas referencias reutilizables de producto, fondo, audio o persona real, continúa con las secciones de la biblioteca de activos.

Ejemplos listos para copiar

Usa el icono de copiar en cualquier bloque de comandos y luego sustituye YOUR_FLATKEY_API_KEY, task_..., ast_... y rph_... por tus propios valores.

Un flujo de trabajo asíncrono

Crea la tarea con POST /v1/videos, consúltala con GET /v1/videos/{task_id} y descarga el MP4 desde metadata.url.

Usa esta cabecera de autorización en cada solicitud de la API de esta guía. La única excepción es la URL de descarga del vídeo devuelta en metadata.url.

Authorization: Bearer YOUR_FLATKEY_API_KEY

Mantén tu clave de API en privado. No la pegues en registros públicos, páginas o tickets de soporte.

Llamar a Seedance

Empieza aquí si solo quieres crear una tarea de texto a vídeo y descargar el vídeo terminado.

1. Crea una tarea de texto a vídeo

Envía POST /v1/videos con el modelo seedance-2.0 y un prompt de texto.

curl -sS https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "Create a calm 5 second video of a ceramic mug on a kitchen table in morning light"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

curl.exe -sS https://router.flatkey.ai/v1/videos `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Content-Type: application/json" `
  -d '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "Create a calm 5 second video of a ceramic mug on a kitchen table in morning light"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

Copia el valor task_... devuelto. Guárdalo en tu base de datos o en tus notas porque lo necesitarás para comprobar el vídeo.

2. Consulta la tarea

Usa este endpoint con el ID de tarea guardado:

GET /v1/videos/{task_id}

Consulta hasta que status sea completed, y entonces lee la URL de descarga en metadata.url. Si el estado es failed, lee error.message, corrige la solicitud y crea una nueva tarea.

TASK_ID="task_3f9a00000000000000000000000000e2"

curl -sS "https://router.flatkey.ai/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

# Run the command above again until status is completed.
# Then copy metadata.url from the response and paste it below.
VIDEO_URL="PASTE_METADATA_URL_HERE"
curl -L "$VIDEO_URL" -o output.mp4

$taskId = "task_3f9a00000000000000000000000000e2"

while ($true) {
  $result = curl.exe -sS "https://router.flatkey.ai/v1/videos/$taskId" `
    -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" | ConvertFrom-Json
  Write-Host "status: $($result.status)"

  if ($result.status -eq "completed") { break }
  if ($result.status -eq "failed") {
    $result | ConvertTo-Json -Depth 10
    exit 1
  }
  Start-Sleep -Seconds 5
}

$videoUrl = $result.metadata.url
curl.exe -L "$videoUrl" -o output.mp4

Una vez que la tarea se ha completado, metadata.url descarga el archivo MP4 sin necesidad de cabecera de autorización. Trata esta URL como privada y no la publiques.

Usa la biblioteca de activos

Usa la biblioteca de activos cuando quieras registrar una referencia una sola vez, esperar hasta que esté lista y reutilizarla en las solicitudes de Seedance. Hay dos tipos de activos:

Tipo de activo	Para qué sirve
Activos virtuales	Imágenes de productos, vídeos de fondo, audio u otras referencias que no sean de personas.
Activos de persona real	El rostro, la voz o el vídeo de una persona específica. Esta capacidad es de acceso limitado y debe habilitarse para tu cuenta.

Usa el URI asset://ast_... devuelto por Flatkey en tus solicitudes de Seedance.

Activos virtuales

Los activos virtuales no requieren verificación de persona real. Créalos a partir de una URL pública o sube un archivo local y luego reutiliza el URI de activo de Flatkey devuelto.

1. Crea un activo virtual a partir de una URL pública HTTPS

Envía una URL pública https://.

curl -sS https://router.flatkey.ai/v1/assets \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://cdn.example.com/reference/product.png",
    "asset_type": "Image",
    "moderation": {
      "strategy": "Default"
    }
  }'

curl.exe -sS https://router.flatkey.ai/v1/assets `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Content-Type: application/json" `
  -d '{
    "url": "https://cdn.example.com/reference/product.png",
    "asset_type": "Image",
    "moderation": {
      "strategy": "Default"
    }
  }'

La respuesta incluye un id, por ejemplo ast_1234567890abcdef1234567890abcdef, y un estado como Processing. Construye el URI reutilizable añadiendo asset:// antes del ID:

asset://ast_1234567890abcdef1234567890abcdef

No envíes model al crear, subir o consultar un activo. Flatkey deriva los modelos de Seedance relevantes a partir de la clave de API utilizada en la solicitud.

2. Sube un activo virtual local

Para un archivo local de imagen, vídeo o audio, envía multipart/form-data a POST /v1/assets/upload. Usa un único campo file. asset_type puede ser Image, Video o Audio.

curl -sS https://router.flatkey.ai/v1/assets/upload \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -F "file=@./reference-a.png" \
  -F "asset_type=Image"

curl.exe -sS https://router.flatkey.ai/v1/assets/upload `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -F "file=@./reference-a.png" `
  -F "asset_type=Image"

La respuesta usa la misma estructura de activo que la creación por URL. Guarda su id o asset_url para las consultas y las solicitudes de vídeo posteriores.

3. Consulta hasta que el modelo seleccionado esté disponible

Consulta cada activo con la misma clave de API que se usará para crear la tarea de vídeo. Por ejemplo, comprueba dos activos de imagen por separado:

curl -sS https://router.flatkey.ai/v1/assets/ast_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"
curl -sS https://router.flatkey.ai/v1/assets/ast_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

curl.exe -sS https://router.flatkey.ai/v1/assets/ast_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"
curl.exe -sS https://router.flatkey.ai/v1/assets/ast_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

Cada respuesta de activo incluye available_models. available_models es siempre un array y enumera los modelos que ya pueden usar este activo. Un activo parcialmente listo puede tener este aspecto:

{
  "id": "ast_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "object": "asset",
  "asset_type": "Image",
  "status": "Processing",
  "available_models": ["seedance-2.0-fast"],
  "asset_url": "asset://ast_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "created_at": 1785292000
}

status es el estado agregado en los modelos de Seedance relevantes para esta clave de API:

Estado	Significado
`Creating`	La subida de origen no ha terminado.
`Processing`	Al menos un modelo relevante todavía se está preparando. Comprueba `available_models`; puede que otro modelo ya sea utilizable.
`Active`	Todos los modelos relevantes para esta clave de API están listos.
`Failed`	El origen falló, o no se pudo determinar la disponibilidad para al menos un modelo relevante.
`Expired`	El origen ya no puede usarse. Crea un nuevo activo.

No necesitas esperar al estado agregado Active si el modelo elegido ya aparece en la lista. Antes de crear una tarea, asegúrate de que el modelo seleccionado aparece en available_models de cada activo. Para la versión rápida usa seedance-2.0-fast; para la versión pro usa seedance-2.0. La solicitud de creación de tarea vuelve a comprobar la disponibilidad, así que reintenta la consulta si el enrutamiento cambió entre las solicitudes GET y POST. El URI asset:// identifica el activo pero no demuestra por sí mismo que esté listo. Deleting significa que la eliminación está en curso y el activo no puede usarse para una nueva tarea. Después de completarse la eliminación, GET /v1/assets/{asset_id} devuelve 404 asset_not_found; no esperes a un estado Deleted consultable.

4. Llama a Seedance con dos activos virtuales

Coloca cada URI asset://ast_... en el campo de medio que coincida con el tipo de activo: image_url.url para Image, video_url.url para Video, o audio_url.url para Audio. Una solicitud de Seedance necesita texto o al menos una imagen/vídeo; el audio por sí solo no es suficiente. Este ejemplo empieza solo después de que ambos activos incluyan seedance-2.0-fast en available_models.

curl -sS https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "content": [
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://ast_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
        },
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://ast_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
        },
        "role": "reference_image"
      },
      {
        "type": "text",
        "text": "Create a clean studio product video while keeping the product consistent"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

curl.exe -sS https://router.flatkey.ai/v1/videos `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Content-Type: application/json" `
  -d '{
    "model": "seedance-2.0-fast",
    "content": [
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://ast_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
        },
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://ast_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
        },
        "role": "reference_image"
      },
      {
        "type": "text",
        "text": "Create a clean studio product video while keeping the product consistent"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

Copia el task_... devuelto y usa GET /v1/videos/{task_id} de la primera sección para descargar el vídeo terminado desde metadata.url.

Activos de persona real

Los activos de persona real son para el rostro, la voz o el vídeo de una persona específica. Esta capacidad es de acceso limitado. Úsala solo después de que Flatkey la habilite para tu cuenta. Crearás un perfil, enviarás verification_url a la persona, esperarás hasta que el perfil esté active, crearás un activo, esperarás hasta que el status del activo sea Active y luego llamarás a Seedance con asset://ast_....

Endpoint	Cuándo usarlo
`POST /v1/real-persons`	Crea un perfil de persona real y el primer enlace de verificación.
`GET /v1/real-persons`	Enumera tus perfiles de persona real.
`POST /v1/real-persons/{person_id}/verification-sessions`	Crea un nuevo enlace de verificación si es necesario.
`GET /v1/real-persons/{person_id}`	Consulta el estado del perfil.
`POST /v1/real-persons/{person_id}/assets`	Crea un activo a partir de una URL pública o un archivo local.
`GET /v1/real-persons/{person_id}/assets`	Enumera los activos de un perfil.

Límites de tamaño de archivo:

Tipo de archivo	Límite
Imagen	< 30 MiB
Vídeo	<= 50 MiB
Audio	<= 15 MiB

Las solicitudes de escritura de esta sección requieren Idempotency-Key. Sustituye cada marcador YOUR_UNIQUE_KEY_... por un nuevo UUID en cada nueva solicitud de escritura. Reutiliza una clave solo cuando reintentes exactamente la misma solicitud.

1. Crea un perfil de persona real

curl -sS https://router.flatkey.ai/v1/real-persons \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_PROFILE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My first real-person profile"
  }'

curl.exe -sS https://router.flatkey.ai/v1/real-persons `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_PROFILE" `
  -H "Content-Type: application/json" `
  -d '{
    "name": "My first real-person profile"
  }'

La respuesta incluye un id de perfil, un status y una verification_url de un solo uso. Envía verification_url a la persona real y pídele que la abra ella misma. No publiques este enlace. Si el enlace caduca o la persona necesita otro enlace, crea una nueva sesión de verificación:

curl -sS -X POST https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/verification-sessions \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_VERIFICATION_SESSION"

curl.exe -sS -X POST https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/verification-sessions `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_VERIFICATION_SESSION"

Después de que la persona termine la página de verificación, continúa con el siguiente paso.

2. Consulta hasta que el perfil esté activo

curl -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

curl.exe -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

Espera hasta que el estado del perfil sea active antes de crear activos. Si es pending_verification o verifying, espera y vuelve a consultar. Si es failed o expired, crea una nueva sesión de verificación.

3. Crea un activo de persona real a partir de una URL pública

curl -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/assets \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_URL_ASSET" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://cdn.example.com/reference/person.png",
    "asset_type": "Image",
    "name": "Front-facing reference"
  }'

curl.exe -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/assets `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_URL_ASSET" `
  -H "Content-Type: application/json" `
  -d '{
    "url": "https://cdn.example.com/reference/person.png",
    "asset_type": "Image",
    "name": "Front-facing reference"
  }'

4. Sube un archivo local

La subida local usa multipart/form-data y solo está disponible para activos de persona real. Usa un único campo file y deja que curl establezca el límite (boundary) multipart.

curl -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/assets \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_FILE_ASSET" \
  -F "asset_type=Image" \
  -F "name=Front-facing reference" \
  -F "file=@./person-reference.png"

curl.exe -sS https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/assets `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_FILE_ASSET" `
  -F "asset_type=Image" `
  -F "name=Front-facing reference" `
  -F "file=@./person-reference.png"

La respuesta de creación incluye un ID de activo o asset_uri, por ejemplo asset://ast_1234567890abcdef1234567890abcdef.

5. Consulta la disponibilidad y llama a Seedance

Las respuestas de activos de persona real no incluyen available_models. Enumera los activos del perfil hasta que el status del activo sea Active:

curl -sS "https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/assets?limit=20" \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

curl.exe -sS "https://router.flatkey.ai/v1/real-persons/rph_1234567890abcdef/assets?limit=20" `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

Si el activo listado sigue en Processing, espera y vuelve a consultar. Si es Failed, crea un nuevo activo a partir de una referencia mejor. Una vez que el activo esté Active, llama a Seedance con el URI asset://ast_....

curl -sS https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "Create a short greeting video with natural movement"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://ast_1234567890abcdef1234567890abcdef"
        },
        "role": "reference_image"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

curl.exe -sS https://router.flatkey.ai/v1/videos `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Content-Type: application/json" `
  -d '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "Create a short greeting video with natural movement"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://ast_1234567890abcdef1234567890abcdef"
        },
        "role": "reference_image"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

Copia el task_... devuelto y usa GET /v1/videos/{task_id} de la primera sección para descargar el vídeo terminado desde metadata.url.

6. Elimina un activo cuando ya no lo necesites

curl -sS -X DELETE https://router.flatkey.ai/v1/assets/ast_1234567890abcdef1234567890abcdef \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

curl.exe -sS -X DELETE https://router.flatkey.ai/v1/assets/ast_1234567890abcdef1234567890abcdef `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

La solicitud de eliminación devuelve 204 No Content. Después de completarse la eliminación, GET /v1/assets/{asset_id} devuelve 404 asset_not_found.

Inicio rápido

Código

Herramientas de IA populares

Generación de medios

Modelos populares

Panel

Referencia

Genera vídeos de Seedance con Flatkey

Ejemplos listos para copiar

Un flujo de trabajo asíncrono

Llamar a Seedance

1. Crea una tarea de texto a vídeo

2. Consulta la tarea

Usa la biblioteca de activos

Activos virtuales

1. Crea un activo virtual a partir de una URL pública HTTPS

2. Sube un activo virtual local

3. Consulta hasta que el modelo seleccionado esté disponible

4. Llama a Seedance con dos activos virtuales

Activos de persona real

1. Crea un perfil de persona real

2. Consulta hasta que el perfil esté activo

3. Crea un activo de persona real a partir de una URL pública

4. Sube un archivo local

5. Consulta la disponibilidad y llama a Seedance

6. Elimina un activo cuando ya no lo necesites

Ejemplos listos para copiar

Un flujo de trabajo asíncrono

​Llamar a Seedance

​1. Crea una tarea de texto a vídeo

​2. Consulta la tarea

​Usa la biblioteca de activos

​Activos virtuales

​1. Crea un activo virtual a partir de una URL pública HTTPS

​2. Sube un activo virtual local

​3. Consulta hasta que el modelo seleccionado esté disponible

​4. Llama a Seedance con dos activos virtuales

​Activos de persona real

​1. Crea un perfil de persona real

​2. Consulta hasta que el perfil esté activo

​3. Crea un activo de persona real a partir de una URL pública

​4. Sube un archivo local

​5. Consulta la disponibilidad y llama a Seedance

​6. Elimina un activo cuando ya no lo necesites

Llamar a Seedance

1. Crea una tarea de texto a vídeo

2. Consulta la tarea

Usa la biblioteca de activos

Activos virtuales

1. Crea un activo virtual a partir de una URL pública HTTPS

2. Sube un activo virtual local

3. Consulta hasta que el modelo seleccionado esté disponible

4. Llama a Seedance con dos activos virtuales

Activos de persona real

1. Crea un perfil de persona real

2. Consulta hasta que el perfil esté activo

3. Crea un activo de persona real a partir de una URL pública

4. Sube un archivo local

5. Consulta la disponibilidad y llama a Seedance

6. Elimina un activo cuando ya no lo necesites