Tutorial de la API de Seedance 2.5 Flash: tareas asíncronas, límites y errores

AIHubMix8 min de lectura
Tutorial de la API de Seedance 2.5 Flash: tareas asíncronas, límites y errores

Usa doubao-seedance-2-5-flash con POST /ai/v1/videos, consulta la tarea y luego descarga el resultado. El esquema actual de AIHubMix admite resultados de 480p/720p, clips de 4–30 segundos y hasta 10 referencias de imagen, 5 de video y 5 de audio. Los clientes antiguos que usan /v1/videos deben cambiar tanto el endpoint como el ID del modelo.

Esta guía se revisó el 16 de noviembre de 2026. Tanto el ID corto anterior como doubao-seedance-2-5-flash-261115 devolvieron un esquema de modelo y rechazaron una solicitud de 1080p con 400 schema_violation. Un intento independiente de crear un clip de 4 segundos a 480p devolvió 402 insufficient_quota; no generó ningún video. El flujo de trabajo que aparece a continuación sigue el esquema y la documentación actuales, pero en esta comprobación no se verificaron de principio a fin la generación correcta, la latencia, la salida MOV ni la edición.

Requisitos previos y descubrimiento del esquema

La página del modelo Seedance 2.5 Flash incluye el modelo con el ID corto que se usa en toda esta guía. Antes de enviar una tarea:

  1. Activa las tareas multimedia asíncronas en la consola de AIHubMix. El error documentado para las cuentas que no tienen esta función es 403 async_not_enabled.
  2. Asegúrate de que la clave de API tenga acceso y de que la cuenta tenga saldo suficiente. La comprobación en vivo devolvió 402 insufficient_quota con el mensaje Your account has insufficient quota. Add credits and try again.
  3. Exporta AIHUBMIX_API_KEY en tu shell. No incluyas la clave en archivos fuente ni en el código del navegador.
  4. Obtén el esquema actual; la solicitud de descubrimiento no requiere autenticación.
curl --fail-with-body -sS \
  'https://aihubmix.com/call/schema/models/doubao-seedance-2-5-flash/endpoints' \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

El esquema del 16 de noviembre solo enumera /ai/v1/videos para Flash. Acepta los valores resolution 480p y 720p (predeterminado: 720p), un valor entero de duration entre 4 y 30, o -1 para que el modelo seleccione la duración. Usa una duración explícita si necesitas un presupuesto predecible.

Crear, consultar y descargar

La API de generación de video de AIHubMix separa la creación, las consultas de estado y las descargas. Una respuesta HTTP correcta al crear una tarea significa que esta fue aceptada; solo status: "completed" confirma que finalizó. Una consulta puede devolver HTTP 200 aunque la tarea tenga status: "failed".

Enviar una tarea de texto a video

Este ejemplo solicita un clip de producto de 10 segundos, 720p y 16:9, con audio. Solo usa texto, así que no depende de imágenes de referencia alojadas en otro sitio.

curl --fail-with-body -sS -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true
  }'

Guarda de inmediato el id de tarea devuelto. Consulta GET /ai/v1/videos/{id} cada 15 segundos hasta que el estado sea completed, failed o cancelled. Para las consultas periódicas mientras la tarea está activa, usa la ruta de detalles del video: esta actualiza el estado del proveedor, mientras que la lista unificada de tareas no sustituye esa consulta. Cuando la tarea termine, descarga el contenido mediante GET /ai/v1/videos/{id}/content, usando el mismo encabezado Bearer.

Un cliente completo en Python

Instala la dependencia con python3 -m pip install requests, guarda lo siguiente como seedance_flash.py y luego ejecuta python3 seedance_flash.py en el shell donde está configurada la clave de API. Este ejemplo implementa el flujo documentado; el error de cuota anterior impidió completar una prueba de generación.

import os
import time
from pathlib import Path

import requests

BASE_URL = "https://aihubmix.com"
HEADERS = {
    "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
    "Content-Type": "application/json",
}
PAYLOAD = {
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": True,
}

# Submit once. A network timeout does not prove that creation failed.
response = requests.post(
    f"{BASE_URL}/ai/v1/videos", headers=HEADERS, json=PAYLOAD, timeout=60
)
response.raise_for_status()
task = response.json()
task_id = task["id"]
print(f"Task ID: {task_id}", flush=True)

deadline = time.monotonic() + 20 * 60
while task["status"] not in {"completed", "failed", "cancelled"}:
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Still waiting for {task_id}; query it again, do not recreate it.")
    time.sleep(15)
    response = requests.get(
        f"{BASE_URL}/ai/v1/videos/{task_id}", headers=HEADERS, timeout=30
    )
    response.raise_for_status()
    task = response.json()

if task["status"] != "completed":
    raise RuntimeError(f"Task {task_id}: {task.get('error') or task['status']}")

response = requests.get(
    f"{BASE_URL}/ai/v1/videos/{task_id}/content", headers=HEADERS, timeout=120
)
response.raise_for_status()
Path("seedance_flash_10s.mp4").write_bytes(response.content)
print("Saved seedance_flash_10s.mp4")

El límite de 20 minutos es un tiempo de espera del lado del cliente, no una cancelación del servidor ni una garantía del tiempo de generación. Si falla la consulta periódica o la descarga, conserva el ID de tarea y vuelve a intentar esa operación. No envíes automáticamente otra solicitud de generación después de un tiempo de espera agotado o si el estado del proveedor no está claro.

Según las tarifas oficiales de inferencia en línea de BytePlus, Flash cuesta $7.00 por millón de tokens sin entrada de video, o $4.30 con entrada de video a 480p/720p. Para el ejemplo que solo usa texto, la estimación es de 10 × 1280 × 720 × 24 / 1024 = 216,000 tokens: $1.51 con Flash frente a $2.31 con el modelo insignia 2.5 a 720p. Son estimaciones calculadas según las tarifas de BytePlus, no una factura de AIHubMix medida.

Referencias y webhooks

Para guiar un clip con contenido multimedia, añade entradas input_references que incluyan un type (image_url, video_url o audio_url) y una url que apunte a contenido multimedia al que se pueda acceder. El esquema limita esos tipos a 10 / 5 / 5. Para controlar el primer y el último fotograma, usa frame_images; cada entrada tiene un frame_type y un image_url.url anidado. No combines frame_images y input_references si ambos contienen elementos. Los flujos de trabajo con fotogramas requieren aspect_ratio: "adaptive", y para especificar un último fotograma también hay que especificar el primero.

La documentación de tareas asíncronas describe las devoluciones de llamada HTTPS mediante webhook_url. El esquema actual de Flash incluye ese campo, pero omite webhook_events_filter y establece additionalProperties: false, así que omite el filtro si sigues este esquema del modelo. Según la documentación, de forma predeterminada se envían los estados completed, failed y cancelled. La entrega es al menos una vez, con hasta seis intentos y tiempos entre reintentos de 1, 4, 16, 64 y 256 segundos; deduplica usando event_id. Las devoluciones de llamada por tarea no tienen un secreto de firma independiente, así que consulta la tarea para confirmar su estado final. La documentación describe suscripciones a nivel de cuenta para las aplicaciones que necesitan verificar la firma.

Errores: lo que se midió y lo que describe la documentación

1080p: rechazo del esquema observado

Ambos ID de modelo de AIHubMix devolvieron HTTP 400 ante una solicitud de 4 segundos con resolution: "1080p". Los campos de error devueltos fueron:

{
  "error": {
    "code": "schema_violation",
    "message": "`resolution` must be one of: 480p, 720p, null.",
    "type": "invalid_request_error"
  }
}

La respuesta también contenía un ID de seguimiento de la solicitud, que se omite aquí. Este es un rechazo observado de la pasarela, no un error ascendente inferido. No demuestra que la generación se haya completado correctamente ni permite medir su velocidad.

Las demás restricciones que aparecen a continuación proceden del esquema actual de Flash; estas combinaciones no válidas no se enviaron por separado durante la comprobación en vivo.

Problema de entrada Requisito del esquema Solución
Salida 4K 480p o 720p Usa una resolución menor
Demasiadas referencias 10 imágenes / 5 videos / 5 audios Reduce el conjunto
Dos matrices de referencias Una sola matriz no vacía Elige un flujo de trabajo
Solo el último fotograma También se requiere el primer fotograma Proporciona ambos fotogramas
Relación de aspecto fija con fotogramas Relación de aspecto adaptativa Usa la opción adaptativa

Referencias de personas reales: usa recursos verificados

AIHubMix documenta el error doubao_real_person_required cuando Doubao devuelve su rechazo de privacidad específico para una imagen de una persona real. Este error no se produjo en esta comprobación. El mensaje documentado es:

Esta solicitud usa una imagen de una persona real. Completa la verificación de personas reales y usa una referencia a un recurso activo. Consulta https://docs.aihubmix.com/cn/api/doubao-real-person-assets.

Sigue la guía de recursos de personas reales de Doubao: crea un grupo en /ai/v1/asset-groups, crea una sesión de verificación en /ai/v1/asset-groups/{id}/verification-sessions, pide a la persona representada que complete la verificación web, registra el recurso en /ai/v1/asset-groups/{id}/assets y espera a que esté activo. Usa asset://<ASSET_ID> en la referencia de generación. Una URL de foto sin más no sustituye el flujo de consentimiento y registro del recurso.

Cuota, tamaño de la solicitud y descargas

El error medido 402 insufficient_quota impidió que la solicitud con una resolución válida llegara a la etapa de generación. Añade saldo antes de volver a intentarlo; cambiar un prompt correcto o el ID del modelo no resuelve este error. 403 async_not_enabled es un error de requisitos previos distinto y documentado que requiere activar la función en la consola.

AIHubMix documenta un límite de 32 MiB para el cuerpo de la solicitud y el error 413 request_too_large. Las URL públicas evitan que la expansión de Base64 aumente el tamaño del cuerpo de la solicitud, aunque el contenido multimedia referenciado aún debe respetar los límites de tamaño y formato del propio modelo.

Guarda pronto el video cuando la tarea haya terminado. La guía de integración de Seedance 2.5 de AIHubMix advierte que las URL de salida caducan rápido, aproximadamente a los 30 minutos; aquí no se verificó un período de retención fijo para Flash. La API de video puede devolver expires_at: null, lo cual no garantiza almacenamiento indefinido. Entre los errores de descarga documentados están 410 artifact_expired y 429 too_many_downloads. Si una descarga devuelve un error temporal del servicio, vuelve a intentar la descarga de la tarea existente en lugar de generar el clip otra vez.

Errores de migración que aún pueden darse con una solicitud válida

La guía de Seedance 2.5 de Volcengine incluye explícitamente Flash en la familia y confirma la salida MOV, la edición y la extensión, pero esas capacidades del proveedor deben distinguirse de lo que se verificó a través de la pasarela.

  • Los campos de MOV y edición están disponibles en el esquema, pero aquí no se probaron de principio a fin. El esquema de Flash acepta extra.output_format: "mp4" o "mov" y los valores auto, reference, edit y extend para extra.omni_reference_task_type. Si envías explícitamente el campo de tipo de tarea, el esquema requiere que input_references no esté vacío. edit también necesita una referencia de video, una relación de aspecto adaptativa y duration: -1; extend necesita una referencia de video y una relación de aspecto adaptativa.
  • El tipo de tarea explícito no garantiza que el modelo lo acepte. Ark documenta el error asíncrono InvalidParameter.TaskTypeConstraint cuando el tipo de tarea inferido y los parámetros entran en conflicto, y InvalidParameter.TaskTypeMismatch cuando el tipo inferido difiere del que se solicitó explícitamente. No se midió la correspondencia exacta en AIHubMix; inspecciona el error devuelto en la tarea en lugar de dar por hecho un código concreto de la pasarela.
  • Flash no admite la promoción desde Draft. El proveedor limita el flujo de trabajo en dos etapas de Draft a 480p y luego a la versión final al modelo insignia 2.5. Flash no lo admite, y los esquemas actuales de AIHubMix para ambos modelos omiten draft y draft_task.
  • La entrada de video cambia la facturación. La facturación oficial se basa en la duración del video de entrada más la de salida y puede aplicar un mínimo de tokens. La tarifa de $4.30/M no garantiza que una tarea guiada por video cueste menos que otra idéntica que solo use texto. Comprueba el uso real y la facturación de la cuenta en lugar de confiar únicamente en la fórmula.
  • Algunas descripciones siguen siendo ambiguas. El esquema de la pasarela de Flash expone extra.priority, extra.safety_identifier y extra.tools, pero sus descripciones aún indican «solo para la serie 2.0». La referencia de creación de tareas de Ark también incluye priority y tools para la familia 2.5. Que estén expuestos en el esquema no verifica por sí solo su efecto en AIHubMix; valida la función específica antes de depender de ella en producción.

Lista de verificación previa

  • Activa las tareas asíncronas y comprueba el saldo de la cuenta.
  • Usa el ID corto de Flash con /ai/v1/videos y consulta su esquema actual.
  • Elige 480p o 720p y una duración explícita de entre 4 y 30 segundos.
  • Limita las referencias a 10 imágenes, 5 videos y 5 clips de audio.
  • Mantén las referencias de fotogramas por separado y usa la relación de aspecto adaptativa para ellas.
  • Usa recursos activos verificados para las referencias de semejanza con personas reales.
  • Guarda el ID de la tarea, consulta su estado terminal y descarga el resultado cuanto antes.
  • Si no tienes certeza sobre el estado de generación, vuelve a consultar la tarea existente o a descargar su resultado.

Preguntas frecuentes

¿Puedo usar la ruta compatible con OpenAI /v1/videos para Flash?
El esquema actual de Flash solo incluye /ai/v1/videos. Usa esa ruta asíncrona nativa para los ejemplos de esta guía.

¿Por qué falla una solicitud con imágenes de fotogramas y aspect_ratio: "16:9"?
El esquema de Flash exige aspect_ratio: "adaptive" cuando se proporcionan valores no vacíos en frame_images. Un fotograma final también requiere un fotograma inicial, y las referencias de fotogramas no se pueden combinar con valores no vacíos en input_references.

¿Cómo puedo solucionar doubao_real_person_required?
Sigue el proceso de verificación personal y registro de recursos, espera a que el recurso esté activo y haz referencia a él mediante un URI de recurso. El código indica un rechazo específico de privacidad de Doubao; no se reprodujo en esta comprobación.

¿Por qué un video de referencia corto puede costar más de lo que predice la fórmula?
Las reglas de facturación del proveedor pueden aplicar un mínimo de tokens cuando la entrada incluye video. La fórmula es una estimación; consulta el consumo real y los registros de facturación de la cuenta para conocer el importe cobrado.

¿Se cobra por las generaciones fallidas o los rechazos de moderación?
Las reglas oficiales de facturación de BytePlus y Volcengine cobran las generaciones exitosas e indican que no facturan las generaciones fallidas ni los rechazos de moderación de contenido. La documentación de errores de AIHubMix aconseja consultar los registros de facturación para ver cargos anteriores; aquí no se midió ninguna factura por una generación exitosa o fallida.

¿Cuánto tiempo tengo para descargar un resultado de Flash?
Descárgalo inmediatamente después de que se complete. La guía existente de Seedance 2.5 advierte que las URL duran aproximadamente 30 minutos, pero no se verificó el período de retención exacto de Flash, y que el campo de expiración sea nulo no significa que el resultado sea permanente.

¿AIHubMix admite la salida MOV y las funciones de edición/ampliación?
El esquema actual de Flash expone los campos correspondientes en extra, y el proveedor documenta estas funciones. No se verificó su funcionamiento integral a través de AIHubMix porque la prueba de creación se detuvo al recibir una respuesta de cuota insuficiente.

Sigue leyendo: la serie Seedance 2.5 Flash

Fuentes

Documentación y esquema consultados el 16 de noviembre de 2026; respuestas de validación registradas a las 08:26 UTC. Los precios son estimaciones oficiales de BytePlus, no cargos medidos de la pasarela.

Un solo gateway para varios proveedores de IA. Diseñado para producción.

Visitar AIHubMix