Materiales de Seedance de TokenLab: Referencias de video reutilizables para flujos de trabajo de producción

Las referencias de video reutilizables son más fáciles de gestionar cuando son activos con un estado de ciclo de vida, no URLs de un solo uso copiadas en cada solicitud de generación. Si alguna vez ha mantenido una hoja de cálculo con enlaces de imágenes, ha vuelto a subir el mismo video de referencia cinco veces o ha vuelto a escribir una URL de intercambio de rostros en tres llamadas de API diferentes, ya entiende el problema que los materiales Seedance están diseñados para resolver.

La biblioteca de materiales Seedance de TokenLab ofrece a los equipos de video una forma, con alcance de organización, de almacenar, verificar y reutilizar referencias en todas las llamadas de generación. Este artículo explica qué es realmente un activo de material, cómo se relacionan los grupos de materiales con los activos individuales, cómo funciona la preparación automática y dónde encaja la verificación de personas reales en el flujo de trabajo.

Puntos clave

• Un activo de material es el objeto de referencia listo para la generación; un grupo de materiales es el contenedor que organiza los activos relacionados, especialmente para flujos de trabajo de personas reales.
• Utilice únicamente el id de un activo de material como material_asset_id (o dentro de material_asset_ids) después de que su estado alcance ACTIVE.
• Existen dos tipos de biblioteca: aigc_avatar para avatares virtuales y otras referencias reutilizables que no son de personas reales, y liveness_face para grupos de materiales de personas reales que requieren verificación.
• TokenLab puede preparar automáticamente entradas de imagen compatibles (image, image_url, image_urls, reference_images, start_image, end_image) en activos de material sin necesidad de un paso de carga independiente.
• Si la preparación supera los 60 segundos, la API devuelve 409 seedance_material_preparing junto con los auto_material_asset_ids que puede consultar y reintentar.
• Seedance 2.0, Seedance 2.0 Fast y Seedance 2.0 Mini son los modelos públicos actuales que admite este sistema de materiales. Verifique los detalles exactos de capacidad por modelo en la documentación antes de crear una dependencia en un nivel específico.

Qué es un material Seedance

Un material Seedance es una referencia reutilizable (imagen, video o audio) que TokenLab almacena como un activo con alcance de organización en lugar de una URL con alcance de solicitud. En lugar de pasar un enlace de archivo sin procesar en cada llamada create-video, usted carga o importa la referencia una vez, espera a que esté lista para la generación y luego la referencia por ID en tantas llamadas posteriores como necesite.

Esto es importante por tres razones prácticas.

Primero, las cargas repetidas desperdician ancho de banda y añaden latencia a cada solicitud, especialmente en el caso de videos de referencia grandes.

Segundo, las URLs sin procesar caducan, se rotan o son revocadas por cualquier sistema de almacenamiento que las alojara originalmente. Un activo de material gestionado por TokenLab no tiene esa fragilidad.

Tercero, y lo más relevante para los equipos que crean canales de video con personajes o marcas consistentes, los materiales le brindan un identificador estable que puede versionar, auditar e intercambiar sin tocar su lógica de generación cada vez.

Activos de material vs. Grupos de materiales

Los dos objetos principales en este sistema son el activo de material y el grupo de activos de material, y es fácil confundirlos si no ha leído detenidamente la referencia de la API.

Un activo de material es un objeto de referencia único: una imagen de avatar, un rostro verificado mediante prueba de vida (liveness), un clip de video de referencia. Cuando lo crea, la API devuelve un id. Ese id es el que finalmente pasa a las llamadas de generación de video una vez que el activo alcanza el estado ACTIVE.

Un grupo de activos de material es un contenedor identificado por group_id. Los grupos organizan los activos relacionados y son estructuralmente necesarios para los flujos de trabajo de personas reales (liveness_face), donde la verificación ocurre a nivel de grupo antes de que se puedan cargar activos individuales en él.

En resumen: group_id organiza; material_asset_id genera. Verá ambos campos en diferentes partes de la API, y usar el incorrecto en el lugar equivocado es el error de integración más común que cometen los equipos con este sistema.

Campo	Qué identifica	Dónde se utiliza
group_id	Un grupo de activos de material (contenedor)	Crear o referenciar un grupo, especialmente para flujos de verificación de personas reales
id (en un activo de material)	Una referencia reutilizable única	Se convierte en material_asset_id una vez que está ACTIVE
material_asset_id	Una referencia de activo única, singular	Se pasa a create-video para una ranura de referencia
material_asset_ids	Una matriz de referencias de activos	Se pasa a create-video cuando se necesitan múltiples referencias reutilizables

Las definiciones completas de los campos y los parámetros requeridos están documentados en las referencias de la API create material asset y create material asset group. Lea esto antes de implementarlo en el código de producción; este artículo cubre la estructura del flujo de trabajo, no todos los parámetros de solicitud.

Flujos de trabajo de avatares virtuales y personas reales

Los materiales Seedance admiten dos tipos de biblioteca, y la distinción no es cosmética: refleja dos posturas diferentes de seguridad y consentimiento.

aigc_avatar: Avatares virtuales y referencias que no son de personas reales

El tipo aigc_avatar cubre referencias reutilizables que no están vinculadas a una persona real verificada: personajes ilustrados, avatares sintéticos, figuras estilizadas, mascotas de marca y activos similares. Estos se pueden crear directamente a través del flujo de creación de activos de material sin un paso de verificación.

Si su producto genera videos sobre personajes ficticios o avatares de marca, este es casi con seguridad el tipo de biblioteca que desea. Tiene una ruta de creación más sencilla porque no tiene un requisito de verificación de identidad asociado.

liveness_face: Grupos de materiales de personas reales

El tipo liveness_face es para grupos de materiales construidos en torno a la imagen de una persona real: el tipo de referencia utilizada para la generación de video con rostros consistentes que presenta a un individuo real. Debido a que esto toca la identidad y el consentimiento, TokenLab requiere un flujo de verificación antes de que los activos puedan cargarse en el grupo.

La secuencia de verificación tiene varios pasos distintos:

1. Creación de sesión: su backend solicita una sesión de verificación para el grupo.
2. Flujo H5: la persona que se está verificando completa una prueba de vida a través de un flujo web alojado (a esto se refiere "H5": una interfaz de verificación web móvil).
3. Callback: TokenLab notifica a su sistema cuando concluye la sesión de verificación.
4. Resultado de vinculación: la identidad verificada se vincula al grupo de materiales.
5. Cargas con alcance de grupo: solo después de que la vinculación sea exitosa se pueden cargar activos de material en ese grupo específico.

Esto significa que los materiales de personas reales son intrínsecamente orientados al grupo: no puede saltar directamente a la creación de un activo como puede hacerlo con aigc_avatar. El grupo debe existir y pasar la verificación antes de que cualquier carga de activos en él sea válida.

Lista de verificación: Elegir el tipo de biblioteca correcto

• ¿La referencia es el rostro o la imagen de una persona real e identificable? → Use liveness_face y planifique el flujo de verificación.
• ¿La referencia es sintética, ilustrada o un avatar que no es de una persona real? → Use aigc_avatar y omita la verificación.
• ¿Su producto necesita una identidad consistente en múltiples generaciones para la misma persona real? → Cree el grupo una vez, verifíquelo una vez, reutilice el grupo para futuros activos.
• ¿No está seguro de en qué tipo cae una referencia suministrada por el cliente? → Trátelo como liveness_face hasta que se confirme lo contrario; verifique en la documentación, no asuma.

No asuma que cada modelo de generación o cada tipo de solicitud admite ambos tipos de biblioteca de manera idéntica; confirme el soporte actual en la guía de modelos de video Seedance 2.0 antes de comprometerse con una arquitectura.

Cómo funciona la preparación automática de materiales

No todas las referencias necesitan un paso de carga manual. TokenLab puede preparar automáticamente entradas de imagen compatibles en activos de material como parte de una solicitud de generación, lo que elimina un viaje de ida y vuelta para casos simples.

Los campos que reconoce para la preparación automática son:

• image
• image_url
• image_urls
• reference_images
• start_image
• end_image

Si pasa cualquiera de estos directamente en una llamada de generación, TokenLab maneja la importación y preparación detrás de escena en lugar de requerir que llame al endpoint de activos de material por separado primero.

Qué sucede cuando la preparación tarda más de 60 segundos

La preparación suele ser rápida, pero las imágenes de referencia más grandes o complejas pueden tardar más en procesarse para convertirse en un activo listo para la generación. Si la preparación supera los 60 segundos, la API responde con:

409 seedance_material_preparing

junto con un campo auto_material_asset_ids que contiene los IDs de los activos que aún se están preparando.

Esto no es un error en el sentido convencional; es una señal para reintentar. Su integración debe tratar 409 seedance_material_preparing como una respuesta de "vuelva a consultar en breve", no como un fallo que deba mostrarse al usuario final. Consulte los IDs de activos devueltos, espere el estado ACTIVE y luego proceda con la generación utilizando esos IDs.

En la práctica, esto significa que su canal de generación necesita un pequeño bucle de reintento, no solo un intento/captura único. Los equipos que crean canales de video automatizados deben tratar este estado de la misma manera que tratarían el retroceso por límite de tasa: esperado, transitorio y manejado en el código en lugar de reportado como un error orientado al usuario.

Cómo usar materiales en la generación

Una vez que un activo de material (ya sea cargado manualmente o preparado automáticamente) alcanza el estado ACTIVE, su id se vuelve utilizable como material_asset_id (o como una entrada en material_asset_ids) en una llamada create video.

El flujo de trabajo principal es el siguiente:

1. Decida si la referencia es de una persona real o no. Elija liveness_face (con verificación) o aigc_avatar según corresponda.
2. Si es una persona real: cree el grupo de materiales, ejecute la sesión de verificación y el flujo H5, reciba el callback y vincule el resultado.
3. Cree o importe el activo de material, ya sea a través de una llamada de carga directa o permitiendo que la preparación automática maneje un campo de imagen compatible dentro de una solicitud de generación.
4. Verifique el estado. No pase el ID del activo a la generación hasta que informe ACTIVE.
5. Si obtiene 409 seedance_material_preparing, consulte los auto_material_asset_ids devueltos y reintente una vez que se resuelvan a ACTIVE.
6. Use el id como material_asset_id o dentro de material_asset_ids en su llamada create-video, apuntando a un modelo Seedance actual como seedance-2.0, seedance-2.0-fast o seedance-2.0-mini según sus necesidades de latencia y calidad.
7. Reutilice el mismo ID de activo en futuras llamadas de generación en lugar de volver a cargar la referencia.

Aquí es también donde la gestión de tareas es importante. Si una llamada de generación basada en un activo de material reutilizado necesita detenerse a mitad de ejecución (por control de costos, un brief creativo cambiado o un mal prompt), consulte nuestro artículo complementario sobre cancelación de tareas Seedance para ver cómo interactúa la cancelación con los trabajos de video en curso.

Para una comparación más amplia de lo que está disponible actualmente en los modelos de generación de video en TokenLab, la página de categoría de modelos de video enumera las opciones actuales una al lado de la otra.

Próximos pasos prácticos

• Si está creando prototipos, comience con materiales aigc_avatar: la ruta de creación es más sencilla y no hay una dependencia de verificación que construir primero.
• Si su producto requiere consistencia de personas reales, cree el flujo de verificación (sesión → H5 → callback → vincular) como una parte fundamental de su incorporación, no como un añadido.
• Agregue un bucle de reintento para 409 seedance_material_preparing antes de enviar nada a producción; trátelo como un comportamiento esperado, no como un caso extremo.
• Almacene los IDs de activos de material junto con sus propios registros de referencia internos para no tener que volver a derivar qué activo corresponde a qué personaje o producto.
• Revise directamente las referencias de la API material asset y material asset group; este artículo describe la forma del flujo de trabajo, y los campos exactos de solicitud/respuesta deben confirmarse con la documentación actual antes de escribir el código de integración.

Puede explorar la biblioteca de materiales directamente en el panel de activos Seedance para ver el estado, el tipo de biblioteca y las relaciones de grupo de los activos que ya ha creado.

Antes de comprometerse con un flujo de trabajo de producción, vale la pena revisar las tarifas actuales en nuestra descripción general de precios de la API de video AI 2026 para comprender cómo escalan los costos con el uso. También puede realizar un seguimiento y exportar sus propios datos de uso utilizando la guía en exportaciones de uso del panel de TokenLab.

Preguntas frecuentes

¿Qué es un activo de material Seedance? Un activo de material es una referencia de generación de video reutilizable (imagen, video o audio) almacenada como un objeto con alcance de organización con su propio estado de ciclo de vida. Una vez que alcanza ACTIVE, puede referenciarlo por ID en múltiples llamadas de generación en lugar de volver a suministrar una URL sin procesar cada vez.

¿Cuál es la diferencia entre group_id y material_asset_id? group_id identifica un grupo de activos de material, que es un contenedor utilizado principalmente para organizar activos de personas reales (liveness_face) y gestionar la verificación a nivel de grupo. material_asset_id identifica una referencia reutilizable única (el id devuelto cuando se crea un activo de material) y es lo que se pasa a las llamadas de generación de video.

¿Cuándo debo usar la verificación de personas reales? Utilice el tipo liveness_face y su flujo de verificación siempre que el material de referencia involucre el rostro o la imagen de una persona real identificable. El flujo requiere la creación de una sesión, una prueba de vida H5, un callback y un paso de vinculación antes de que se puedan cargar activos en ese grupo. Las referencias que no son de personas reales, como avatares ilustrados o sintéticos, utilizan aigc_avatar y no requieren esta ruta de verificación.

¿Qué significa seedance_material_preparing? Es una respuesta 409 devuelta cuando la preparación automática de material (activada por campos de imagen compatibles como image_url o start_image en una solicitud de generación) tarda más de 60 segundos en completarse. La respuesta incluye auto_material_asset_ids para que pueda consultar esos IDs y reintentar la generación una vez que estén ACTIVE. Señala un estado transitorio en curso, no un fallo.

Fuentes y actualidad

• Guía de modelos de video Seedance 2.0 — https://docs.tokenlab.sh/guides/seedance-2-video — observado el 09-07-2026
• Crear activo de material Seedance (referencia de API) — https://docs.tokenlab.sh/api-reference/video/create-material-asset — observado el 09-07-2026
• Crear grupo de activos de material Seedance (referencia de API) — https://docs.tokenlab.sh/api-reference/video/create-material-asset-group — observado el 09-07-2026
• Crear video (referencia de API) — https://docs.tokenlab.sh/api-reference/video/create-video — observado el 09-07-2026
• Panel de activos Seedance de TokenLab — https://tokenlab.sh/en/dashboard/seedance-assets — observado el 09-07-2026

El comportamiento de la API, los nombres de los campos y la semántica de estado descritos aquí reflejan la documentación pública y la copia del panel a partir de la fecha observada. El sistema de materiales Seedance de TokenLab está en desarrollo activo; confirme los nombres de los parámetros actuales, los valores de estado y el soporte específico del modelo en la documentación vinculada antes de finalizar el código de integración de producción.

Si está creando un canal de video que depende de referencias estables y reutilizables, comience con la guía de modelos de video Seedance 2.0: es la forma más rápida de ver los nombres de los parámetros actuales y confirmar qué admite realmente su nivel de modelo objetivo.