how-tos

Seedance 2.5 API: guía para llamar a Seedance 2.5 Flash con cURL y Python

Poyo.ai Team
12 min read
Share:

Un mensajero en bicicleta compitiendo con la torre del reloj al amanecer, ilustración editorial para la guía de la Seedance 2.5 Flash API

La Seedance 2.5 Flash API es el nivel más rápido y económico de la Seedance 2.5 API, y en PoYo corresponde a un único ID de modelo: seedance-2.5-flash. ByteDance lo lanzó el 12 de noviembre de 2026; la página del modelo Seedance 2.5 Flash tiene el playground y los precios actualizados. Esta guía te lleva desde una primera solicitud con cURL hasta un bucle de producción en Python, usando el esquema de la documentación de la Seedance 2.5 Flash API revisado el 16 de noviembre de 2026.

Seedance 2.5 Flash API de un vistazo

ElementoValor
Endpoint de envíoPOST https://api.poyo.ai/api/generate/submit
Endpoint de estadoGET https://api.poyo.ai/api/generate/status/{task_id}
Cabecera de autenticaciónAuthorization: Bearer $POYO_API_KEY
ID de modeloseedance-2.5-flash (el slug de página seedance-2-5-flash no es un ID de modelo)
Campos obligatoriosprompt, duration
DuraciónSegundos enteros, 4–30
Resolución480p o 720p, por defecto 720p
Relación de aspectoauto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, por defecto auto
Audiogenerate_audio, por defecto true
EntregaTarea asíncrona: consulta el estado o define callback_url

Tu primera solicitud a la Seedance 2.5 API con cURL

Exporta tu clave como POYO_API_KEY y guárdala en el servidor, nunca en código de navegador. Esta es una solicitud de texto a vídeo de 5 segundos en 480p, una primera prueba de bajo coste por 92,5 créditos:

curl --fail-with-body https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5-flash",
    "input": {
      "prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot, gentle water sounds, no speech, no subtitles.",
      "duration": 5,
      "resolution": "480p",
      "aspect_ratio": "16:9"
    }
  }'

Un envío correcto devuelve code: 200 y un objeto data con task_id, status (siempre not_started justo después del envío) y created_time. Es un justificante, no un vídeo. Guarda el task_id y después consúltalo:

curl --fail-with-body \
  https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Los estados pasan por not_started, running, finished y failed. Cuando la tarea está en finished, la URL del vídeo está en data.files[].file_url con file_type: "video"; si está en failed, lee data.error_message. Los archivos generados siguen accesibles durante 3 días, así que cópialos a tu propio almacenamiento.

Python: enviar y consultar con un plazo máximo estricto

La documentación de estado recomienda consultar cada 2–5 segundos, aplicar backoff ante 429 y 5xx, y definir siempre un tiempo de espera máximo. El bucle siguiente hace las tres cosas y nunca vuelve a enviar la tarea al agotarse el tiempo, porque un segundo envío es una segunda tarea facturable.

import os
import time
import requests

BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]


def checked(response):
    try:
        body = response.json()
    except ValueError:
        response.raise_for_status()
        raise
    if body.get("code") != 200:
        err = body.get("error") or {}
        raise RuntimeError(
            f"PoYo {body.get('code')} {err.get('type')}: "
            f"{err.get('message') or body.get('detail')}"
        )
    return body["data"]


task = checked(session.post(BASE + "/api/generate/submit", json={
    "model": "seedance-2.5-flash",
    "input": {
        "prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
        "duration": 5,
        "resolution": "480p",
        "aspect_ratio": "16:9",
    },
}, timeout=60))
task_id = task["task_id"]
print("Saved task:", task_id, flush=True)

deadline = time.monotonic() + 15 * 60
backoff = 5
while time.monotonic() < deadline:
    r = session.get(f"{BASE}/api/generate/status/{task_id}", timeout=60)
    if r.status_code == 429 or r.status_code >= 500:
        time.sleep(backoff)
        backoff = min(backoff * 2, 60)
        continue
    data = checked(r)
    if data["status"] == "failed":
        raise RuntimeError(data.get("error_message") or "Generation failed")
    if data["status"] == "finished":
        videos = [f["file_url"] for f in data.get("files", [])
                  if f.get("file_type") == "video"]
        print(videos[0], "credits:", data.get("credits_amount"))
        break
    backoff = 5
    time.sleep(5)
else:
    raise TimeoutError("Still running; poll the saved task ID later: " + task_id)

Como referencia, en las pruebas de PoYo del 16 de noviembre de 2026, un clip de 4 segundos en 480p terminó en unos dos minutos y un clip de 30 segundos en 720p en menos de tres minutos, de principio a fin. Los tiempos varían según la carga, así que el plazo de 15 minutos es un límite de seguridad, no una estimación.

Evita el sondeo: usa callback_url

Añade un callback_url en el nivel superior, junto a model. Cuando la tarea pasa a finished o failed, PoYo envía un POST cuyo cuerpo es el objeto de datos de la tarea (task_id, status, files, created_time, error_message) sin el envoltorio code/data. Según la documentación de webhooks de vídeo:

  • La URL debe ser HTTPS pública, de 2048 caracteres como máximo y sin IP privadas.
  • Responde con un 2xx en 30 segundos; las entregas fallidas se reintentan hasta 5 veces con backoff exponencial.
  • Verifica X-Webhook-Signature como base64(HMAC-SHA256(task_id + "." + timestamp, key)), con timestamp tomado de X-Webhook-Timestamp y la clave obtenida de GET /api/api-keys/webhook-secret.
  • Haz que el handler sea idempotente. Si fallan todos los reintentos, el endpoint de estado sigue teniendo el resultado.

Los tres modos de entrada, con cuerpos JSON

La API elige el modo según los archivos multimedia que envíes. No existe un campo mode.

ModoSe selecciona cuandoRelación de aspecto
Referencia a vídeoCualquiera de reference_image_urls, reference_video_urls, reference_audio_urls no está vacíoCualquier valor admitido
Imagen a vídeo (primer/último fotograma)image_urls no está vacíoauto u omitirlo; la salida sigue al primer fotograma
Texto a vídeoSin archivos multimediaCualquier valor admitido

image_urls y los campos de referencia van en solicitudes separadas. Estos cuerpos son los ejemplos documentados.

Texto a vídeo (30 segundos en 720p, con una lista de planos temporizada en el prompt):

{
  "model": "seedance-2.5-flash",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "One continuous 30-second story of the same young woman in a yellow raincoat delivering a handwritten letter across a small seaside town at dawn. 0-6s: wide aerial shot of the sleepy harbor town, fishing boats rocking, soft morning light; she rides an old bicycle down a cobblestone hill. 6-12s: tracking shot beside her as she weaves past a fish market, seagulls lifting off, a vendor waves at her. 12-18s: low-angle shot as she climbs a steep stone staircase carrying the bicycle, breathing hard, the letter tucked in her pocket. 18-24s: she knocks on a blue door at the top; an elderly man opens it and she hands him the letter. 24-30s: close-up of the man reading, his eyes filling with tears; he smiles and says softly, \"She remembered.\" Camera slowly pulls back to reveal the sunrise over the sea. Natural ambient sound: waves, gulls, bicycle bell, footsteps, gentle piano music. No subtitles, no on-screen text.",
    "duration": 30,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}

Primer y último fotograma (una URL fija el inicio; una segunda fija el final):

{
  "model": "seedance-2.5-flash",
  "input": {
    "prompt": "Locked-off time-lapse of the red lakeside cabin: start from the summer evening in the first frame, let snow gradually cover the shore and the wooden dock as the sky darkens, and end exactly on the snowy night with the aurora in the last frame. Soft wind and crackling ice.",
    "image_urls": [
      "https://example.com/first-frame.jpg",
      "https://example.com/last-frame.jpg"
    ],
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "auto"
  }
}

Referencia a vídeo (refiérete a los archivos por orden de subida como @Image1, @Video1, @Audio1):

{
  "model": "seedance-2.5-flash",
  "input": {
    "prompt": "@Image1 is the ginger cat. It wears the yellow knitted scarf from @Image2 and is inside the bookstore from @Image3. On a rainy night the cat walks along a bookshelf, jumps down beside a reading lamp, and looks at the camera. Match the slow, cozy rhythm of @Audio1. No subtitles.",
    "reference_image_urls": [
      "https://example.com/cat.png",
      "https://example.com/scarf.png",
      "https://example.com/bookstore.png"
    ],
    "reference_audio_urls": [
      "https://example.com/rhythm.mp3"
    ],
    "duration": 6,
    "resolution": "480p",
    "aspect_ratio": "16:9"
  }
}

Reglas de validación que conviene aplicar antes de enviar

Comprobar esto en el cliente ahorra un viaje de ida y vuelta y da a tus usuarios un mensaje más claro que un 400 genérico.

CampoRegla
promptObligatorio, cadena no vacía
durationEntero obligatorio, 4–30
resolutionSolo 480p o 720p; 1080p requiere seedance-2.5
aspect_ratioUno de los siete valores; con image_urls, usa auto u omítelo
image_urls1–2 URL (primer fotograma y después último); JPEG, PNG o WebP, hasta 30 MB cada una; no se combina con los campos de referencia
reference_image_urlsHasta 10; JPEG, PNG o WebP, hasta 30 MB cada una
reference_video_urlsHasta 5; MP4 o MOV, de 2–30 s y hasta 200 MB cada uno; duración combinada de 30 s como máximo
reference_audio_urlsHasta 5; MP3 o WAV, de 2–30 s y hasta 15 MB cada uno; duración combinada de 30 s como máximo; requiere una imagen o un vídeo de referencia
Todas las URL multimediaHTTP o HTTPS públicas, descargables directamente (sin páginas de inicio de sesión ni vistas previas que caduquen)

Las duraciones combinadas de las referencias se comprueban al enviar la tarea. El esquema también define additionalProperties: false en input, así que no envíes campos de las API de otros proveedores, como seed o negative_prompt.

Errores que conviene gestionar

Lee siempre el campo code del cuerpo: algunos errores de validación del endpoint de envío llegan con HTTP 200 y "code": 400. La referencia de códigos de error enumera estos:

CódigoTipoQué hacer
400validation_error, file_format_error, content_moderation_errorCorrige la solicitud o los archivos; no reintentes sin cambios
401authentication_errorRevisa la cabecera Bearer y que la clave siga existiendo
402insufficient_credits_errorRecarga y vuelve a enviar
429Límite de tasaAplica backoff (1 s, 2 s, 4 s...) antes de volver a consultar o enviar
500, 502, 503Servidor o proveedor upstreamReintenta la consulta de estado con backoff; comprueba el estado antes de volver a enviar
Tarea failederror_message definidoRegistra el ID de tarea; las tareas fallidas indican credits_amount: 0

Cómo se calcula la primera factura

Sin vídeos de referencia, el coste es igual a los segundos de salida por la tarifa por segundo: 18,5 créditos (0,0925 $) en 480p y 41 créditos (0,205 $) en 720p, con 1 crédito = 0,005 $. El audio generado no añade coste.

Solicitud anteriorSegundos facturadosCréditosUSD
Prueba con cURL, 5 s 480p592.5$0.4625
Texto a vídeo, 30 s 720p301,230$6.15
Primer/último fotograma, 5 s 720p5205$1.025
Imágenes de referencia + audio, 6 s 480p6111$0.555

Añadir cualquier reference_video_urls cambia a la tarifa con vídeo, más baja (11,5 créditos en 480p, 25,5 en 720p), aplicada a los segundos facturados: la duración de la salida más la duración de cada vídeo de referencia redondeada a la baja a segundos enteros. El desglose de precios de la Seedance 2.5 API analiza esos casos. El cargo de una tarea terminada aparece como credits_amount en la respuesta de estado.

Pasa a Seedance 2.5 para 1080p

Los campos de la solicitud son los mismos, así que pasar un trabajo de Flash al modelo Seedance 2.5 estándar consiste en cambiar el ID de modelo:

{
  "model": "seedance-2.5",
  "input": {
    "prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9"
  }
}

Dos detalles: la documentación de seedance-2.5 indica resolution como obligatorio, así que envíalo siempre, y el modelo estándar admite hasta 30 imágenes, 10 vídeos y 10 audios de referencia. En 1080p cuesta 114 créditos (0,57 $) por segundo. Para decidir el enrutamiento, consulta Seedance 2.5 Flash frente a Seedance 2.5; para ver cómo se compara Seedance 2.5 con otro proveedor, consulta Kling 4.0 frente a Seedance 2.5.

Preguntas frecuentes

¿Cuál es el ID de modelo de la Seedance 2.5 Flash API? seedance-2.5-flash, con puntos. seedance-2-5-flash, con guiones, es solo el slug de la página del modelo.

¿La Seedance 2.5 Flash API admite 1080p? No. Acepta 480p y 720p. Envía el mismo cuerpo con "model": "seedance-2.5" y "resolution": "1080p" para obtener 1080p nativo.

¿Cómo desactivo el audio en la Seedance 2.5 API? Define "generate_audio": false para obtener un clip sin sonido, o mantén el audio activado y elimina capas concretas en el prompt, por ejemplo con «no background music».

¿Puedo usar primeros fotogramas e imágenes de referencia en una misma solicitud a Seedance 2.5 Flash? No. image_urls y los campos reference_* deben enviarse en solicitudes separadas.

¿Cuánto tarda una tarea de la Seedance 2.5 Flash API? En la prueba de PoYo del 16 de noviembre de 2026, unos dos minutos para 4 segundos en 480p y menos de tres minutos para 30 segundos en 720p, de principio a fin. Consulta el estado o usa un callback en lugar de mantener una solicitud abierta.

¿Se me cobra si falla una tarea de Seedance 2.5 Flash? No. Las tareas fallidas no se cobran y su estado muestra credits_amount: 0.

Share: