Seedance: API de generación de video

Modelos disponibles

En 2.5 internacional, 1080p solo está disponible si su grupo lo admite, y 4K no se admite.

Los modelos de China los sirve el grupo Seedance China (Doubao) y los internacionales el grupo Seedance internacional + Seedream. El grupo de China cubre Estándar, Fast, Mini y Seedance 2.5; solo 4K requiere el modelo Estándar internacional. Las claves internacionales no pueden llamar a los ID doubao-*.

Los precios por tramo y las especificaciones completas de cada modelo están en su ficha, por ejemplo dreamina-seedance-2-5-260628 y doubao-seedance-2-0-260128-a.

Parámetros de la solicitud

Todos son campos JSON de nivel superior: no los anide dentro de parameters. Enteros y booleanos enviados como cadenas ("5", "true") o enteros enviados con decimales se rechazan. El cuerpo completo admite hasta 64 MB, Data URL incluidas.

frames, seed, camera_fixed, draft, draft_task y service_tier se rechazan (400) en ambas generaciones. Todos los campos también están en Referencia de la API: enviar tarea de video.

Elementos de content

Los elementos de content son text / image_url / video_url / audio_url:

"content": [
  { "type": "text", "text": "Un gato naranja corre por el pasto, la cámara lo sigue" },
  { "type": "image_url", "image_url": { "url": "https://example.com/cat.png" }, "role": "reference_image" },
  { "type": "video_url", "video_url": { "url": "https://example.com/ref.mp4" } },  // role por defecto: reference_video
  { "type": "audio_url", "audio_url": { "url": "https://example.com/ref.mp3" } }   // role por defecto: reference_audio
]

El role de una imagen es first_frame, last_frame o reference_image:

• Una sola imagen sin role se trata como primer fotograma.
• Varias imágenes deben indicar role.
• Si hay una referencia de video o audio, las imágenes deben ser reference_image.
• El modo de fotogramas admite como máximo 2 imágenes: una sola debe ser first_frame, dos deben ser un first_frame y un last_frame, y no se mezcla con referencias.
• En Seedance 2.0 el audio de referencia debe ir con una imagen o un video; 2.5 admite solo audio.

Imágenes y audio pueden ir como Data URL base64; el video no. Seedance 2.0 también acepta un asset://asset-id ya disponible.

Especificaciones de los medios de referencia

Estas reglas se aplican a Seedance 2.0 y 2.5, China e internacional, no a todos los modelos de video.

Cada referencia se descarga y comprueba al enviar; si no cumple, devuelve de inmediato un 400 (sin code; identifíquelo por message) y no genera costo de tarea. Un medio que pasa la comprobación aún puede fallar después por la revisión de contenido.

El modo de fotogramas admite como máximo 2 imágenes. El total combinado de video y de audio tiene el mismo límite que cada clip y se cuenta por separado, no se suma: en 2.0 todos los videos de referencia juntos deben durar ≤ 15 segundos, todo el audio de referencia también ≤ 15 segundos, y cada clip ≥ 2 segundos.

La duration del resultado y la duración de las referencias son límites independientes. 1 MiB = 1,048,576 bytes.

URL del medio debe ser una dirección http(s) accesible públicamente:

• Las direcciones privadas / loopback / link-local y las URL con credenciales se rechazan.
• Se siguen como máximo 3 redirecciones.
• Cada medio debe descargarse y analizarse en 2 minutos.
• Las Data URL deben ser data:<MIME>;base64,….

Biblioteca (solo Seedance 2.0)

La biblioteca recibe una URL pública existente y devuelve un ID, que se referencia como asset://asset-id en la generación de Seedance 2.0. Las referencias normales también pueden enviarse por URL directa sin registro.

curl https://api.hop-base.com/v1/sd/assets \
  -H "Authorization: Bearer sk-tu-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "URL": "https://example.com/your-image.jpg",
    "Name": "character_front",
    "AssetType": "Image"
  }'

{
  "data": {
    "Id": "assetEXAMPLE"
  }
}

curl https://api.hop-base.com/v1/sd/assets/assetEXAMPLE \
  -H "Authorization: Bearer sk-your-key"

{
  "data": {
    "Id": "assetEXAMPLE",
    "Status": "Active",
    "AssetType": "Image"
  }
}

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "dreamina-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "The subject waves gently at the camera"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://assetEXAMPLE"
      },
      "role": "reference_image"
    }
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9"
}'

Campos de la solicitud de subida:

La subida descarga el medio y lo comprueba con las reglas de 2.0 de "Especificaciones de los medios de referencia", así que video y audio deben durar 2–15 segundos. Los 400 de la subida sí incluyen error.code (por ejemplo invalid_asset_duration).

Adapte el elemento de content al tipo de medio:

• Video: type: video_url, video_url.url: asset://… y role: reference_video.
• Audio: audio_url / reference_audio.
• Para primer/último fotograma use first_frame / last_frame; no mezcle fotogramas con referencias multimodales.

No modifique los ID ni los reutilice entre grupos o usuarios. La generación vuelve a comprobar estado, tipo, cantidades y especificaciones; registrar no evita los límites de 2.0 ni la moderación.

Respuesta

Las respuestas de envío y de consulta de una tarea van dentro de task; no lea id / outputs en el nivel superior.

Respuesta al enviar

Un envío correcto devuelve 200 con un task.id como vt… para las consultas posteriores. La respuesta de envío solo contiene id, model, status (pending o processing), outputs (siempre vacío), error, created_at y completed_at; obtenga los resultados consultando la tarea.

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "dreamina-seedance-2-5-260628",
    "status": "pending",
    "outputs": [],
    "error": null,
    "created_at": "2026-09-23T08:00:00Z",
    "completed_at": null
  }
}

Campos de la consulta

task.status siempre es uno de estos cuatro valores. Lea task.outputs solo con completed: una tarea solo informa completed cuando sus enlaces de resultado están listos, y entonces outputs nunca está vacío. Con pending / processing, siga consultando; se recomienda cada 5 segundos.

La generación en 480p y 720p suele tardar de 2 a 5 minutos; 1080p y 4K tardan más. Las URL de salida admiten reproducción en navegador y solicitudes Range y caducan 30 días después de completarse.

En curso

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "dreamina-seedance-2-5-260628",
    "status": "processing",
    "outputs": [],
    "error": null,
    "created_at": "2026-09-23T08:00:00Z",
    "completed_at": null
  }
}

Completada

Fragmento de una tarea completada (HTTP 200); ID, URL y uso son ilustrativos:

{
  "task": {
    "id": "vtEXAMPLE",                       // ID de tarea de HopBase
    "model": "dreamina-seedance-2-5-260628",
    "status": "completed",
    "duration_seconds": 5,                   // en tareas de duración automática, léalo al terminar
    "outputs": ["https://api.hop-base.com/example-signed-video.mp4"],  // arreglo de cadenas, no objetos {url}
    "last_frame_url": "https://api.hop-base.com/example-signed-last-frame.jpg",  // opcional, solo si hay último fotograma
    "usage": { "completion_tokens": 1000, "total_tokens": 1000 },  // opcional; tokens, no un importe
    "error": null,
    "created_at": "2026-09-23T08:00:00Z",
    "completed_at": "2026-09-23T08:03:10Z"   // null hasta terminar
  },
  "usage": { "cost": 3.4, "currency": "CNY", "cost_cny": 3.4, "cost_usd": 0.5 }
}

Fallida

Si la generación falla, la consulta sigue devolviendo HTTP 200 con status failed y el motivo en task.error.message. Las tareas fallidas no se facturan.

{
  "task": {
    "id": "vtEXAMPLE",
    "status": "failed",
    "outputs": [],
    "error": { "message": "<English failure reason>" }
  }
}

El message está en inglés y no tiene campo code. Los enlaces se sustituyen por [URL_REDACTED] y se quitan los identificadores de solicitud y los códigos de error internos; si no hay motivo disponible, es un texto genérico en inglés.

Lista de tareas

GET /v1/video/tasks admite ?page=1&limit=20 y devuelve {"tasks": [...], "total": 1, "totalPages": 1}, donde cada elemento es un objeto de tarea. El limit es 20 por defecto (máximo 100) y solo incluye tareas enviadas por la API.

Ejemplo mínimo

# 1. Enviar
curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-tu-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "content": [
      { "type": "text", "text": "Un gato naranja corre por el pasto iluminado por el sol mientras la cámara lo sigue" }
    ],
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": false,
    "watermark": false
  }'

# 2. Consulte con el task.id devuelto; se recomienda cada 5 segundos
curl https://api.hop-base.com/v1/video/tasks/vt-tu-task-id \
  -H "Authorization: Bearer sk-tu-clave"

Notas

Modo de tarea de Seedance 2.5

Seedance 2.5 no tiene un parámetro explícito de modo de tarea. Cuando la solicitud incluye un reference_video, Seedance la clasifica como generación ordinaria, extensión de video o edición de video según el texto del prompt. Un prompt de continuación ("continúa este clip", "extiende la toma") se trata como extensión de video.

El mensaje es como identified your task as video extension based on your prompt. Seedance 2.0 no tiene modo de extensión ni de edición y no se ve afectado.

Imágenes de referencia con personas reales

Seedance 2.0: suba la misma imagen a la biblioteca (vea "Biblioteca" arriba) y, cuando esté lista, referénciela como asset://asset-id. Si necesita una referencia de persona real, use 2.0 con la biblioteca. Registrar no evita el resto de la revisión de contenido.

Tiempo límite, cancelación y enlaces de resultado

• Una tarea que sigue sin terminar 24 horas después de crearse pasa automáticamente a fallida, sin cargo.
• Las tareas de video no se pueden cancelar; tras un envío correcto no vuelva a enviar, porque cada reenvío es otra tarea facturable.
• Las URL de salida son URL firmadas en api.hop-base.com, válidas 30 días desde que termina la tarea; volver a consultar no las prolonga y una URL caducada devuelve 410.

Pasar del grupo internacional al de China

El grupo de China también acepta los IDs internacionales dreamina-* de la tabla como alias de compatibilidad (4K se sigue rechazando). Los clientes existentes que pasen al grupo de China solo cambian la clave: la base_url, las rutas de la API, los parámetros y la lógica de polling no cambian.

Tras el cambio, llame a GET /v1/models con la nueva clave para elegir el ID de modelo completo. Las tareas enviadas antes siguen siendo consultables con su ID original.

Errores comunes y soluciones

Tres formas copiadas de otras APIs se rechazan directamente:

Errores de parámetros al enviar

Estos errores devuelven 400 de forma síncrona; no se crea tarea ni se factura. El cuerpo es {"error":{"message":"…","type":"invalid_request_error"}} sin campo code, así que identifíquelos por message (números e índices varían):

# Tipos y valores
duration must be an integer                    # igual para priority / execution_expires_after
watermark must be a boolean                    # igual para generate_audio / return_last_frame
Seedance 2.0 duration must be an integer in 4-15 or -1, got 20
Seedance 2.5 duration must be an integer in 4-30 or -1, got 40
model dreamina-seedance-2-0-hc does not support parameter seed   # campo rechazado; nombra el modelo solicitado
model dreamina-seedance-2-0-hc does not support ratio 2:1
model dreamina-seedance-2-0-fast-hc does not support resolution 1080p
request body must not exceed 64MB
priority must be within 0-9, got 10
execution_expires_after must be within 3600-259200 seconds
callback_url must be a valid http(s) URL
safety_identifier must be an ASCII string of 1-64 characters

# Estructura de content
missing content                                # solo se envió un prompt de nivel superior
content[0].image_url must be an object         # image_url enviado como cadena
content[0].type does not support image         # type enviado como image / input_image
content[0].text must not be empty
multi-image scenarios must specify first_frame/last_frame or reference_image roles
images in a multimodal reference scenario must set role=reference_image
first/last frame image-to-video cannot be mixed with the multimodal reference scenario
Seedance 2.0 supports at most 9 reference images

# Modelo y grupo
domestic doubao-seedance-2-0-fast-260128-a only supports 480p, 720p, got 1080p
model seedream-5-0-pro is an image generation model, use POST /v1/images/generations instead

Dos casos no son el 400 anterior:

El 404 llega antes que estas validaciones; tome los ID válidos de GET /v1/models.

Errores de medios de referencia

content[1] es el índice del elemento en content:

content[1] media URL returned HTTP 403        # el servidor rechazó la descarga (antihotlink, firma caducada…)
content[1] unable to fetch media file, make sure the URL is publicly accessible
content[1] media URL hostname could not be resolved
content[1] media URL must point to a public address, not a private or reserved one
content[1] too many redirects for media URL
content[1] unable to parse media metadata of the video asset   # archivo dañado o formato incorrecto
content[1] media data URL must be base64-encoded
content[1] image data URL does not support MIME type image/svg+xml
    # permitidos: image/jpeg png webp bmp tiff gif heic heif; audio/wav audio/mpeg
content[1] reference image width and height must be within 300-6000 px, got 200x200
content[1] video asset duration must be within 2-15 seconds, got 16.000 seconds
total reference video duration must not exceed 15 seconds, got 18.000 seconds

Si una referencia no se puede descargar y analizar en 2 minutos, el envío devuelve 503 con code upstream_timeout:

media validation timed out, please retry later

Es una condición temporal del servicio, no un problema de su medio: reintente la misma solicitud más tarde.

Los errores al referenciar recursos de la biblioteca también son 400 síncronos sin code:

content[1] reference asset is not ready yet, current status is Processing  # siga consultando; envíe cuando esté Active
content[1] requires a image asset, got Video       # AssetType no coincide con image_url / video_url / audio_url
content[1] references a retired Seedance 2.5 EP asset; ...  # asset25-* está retirado; envíe la URL pública original
... cannot be mixed in one task                    # use recursos de una misma subida o envíe URL públicas

Motivos de fallo de la tarea

OutputVideoSensitiveContentDetected / OutputAudioSensitiveContentDetected  # la salida no pasó la revisión; PolicyViolation = derechos de autor
rejected by content moderation                                             # el video generado, el prompt o el medio de referencia no pasó la moderación
InputImageSensitiveContentDetected y otros Input…Sensitive…                 # el medio de entrada no pasó la revisión (incl. privacidad de personas reales)
InvalidParameter / is not valid / missing required / identified your task as  # parámetro o modo de tarea no válido
task no longer exists                                                        # la tarea ya no existe
task expired / timed out / did not finish within 24 hours                     # la tarea caducó

Los fallos de revisión y de parámetros (los cuatro primeros) vuelven a fallar si se reenvían sin cambios: corrija antes el prompt, el medio o el parámetro. Los dos últimos pueden reenviarse tal cual.

Facturación

Seedance factura por tokens de video; task.usage.completion_tokens contiene el conteo de tokens facturables. Las tareas fallidas y los 400 al enviar no se facturan.

Al enviar se reserva saldo por el costo estimado y se libera al terminar la tarea. Con duration: -1, 2.5 reserva saldo para 30 segundos y 2.0 para 15; si el saldo es justo, envíe una duración concreta para reservar menos. Las reglas de saldo y el campo usage.cost están en el resumen de video; los precios oficiales, en la tabla de modelos y las fichas; el cargo real, en la página Consumo de la consola.

Próximos pasos

• Resumen de video: comparación de las familias de video y el flujo de tareas común
• Referencia de la API: enviar tarea de video: campos de la solicitud
• Referencia de la API: consultar tarea de video: campos de la respuesta
• Códigos de error y reintentos: qué significa cada código de error y si conviene reintentar