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

Si su equipo alguna vez ha pegado la misma URL de intercambio de rostros (face-swap) en tres llamadas de API diferentes, ya sabe por qué existe la biblioteca de materiales de Seedance. Las referencias de video reutilizables funcionan mejor como activos con un estado de ciclo de vida que como URLs de un solo uso copiadas de una hoja de cálculo en cada solicitud de generación. TokenLab asigna esos activos a su organización, para que pueda almacenar, verificar y reutilizar referencias en todas las llamadas. Probamos la estructura del flujo de trabajo: los grupos organizan el material de personas reales, los activos contienen la referencia real y las llamadas de generación consumen los IDs solo después de que el estado llega a ACTIVE. Por ejemplo, un equipo que antes mantenía una hoja de cálculo de enlaces de imágenes y volvía a cargar el mismo video de referencia cinco veces puede reemplazar ese hábito con un solo ID de activo de material.

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 el id de un activo de material como material_asset_id (o dentro de material_asset_ids) solo después de que su estado llegue a 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 un paso de carga por separado.
• 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 es la familia de modelos públicos actual 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.

Biblioteca de materiales de Seedance: Activos y grupos

Un material de 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 para 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 que gestiona 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 tener que 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. 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 por vivacidad (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. 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. 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 usa
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 de crear activo de material y crear grupo de activos de material. Léalas antes de integrar esto en el código de producción. La documentación 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 de Seedance admiten dos tipos de biblioteca. 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. Puede crearlos 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 hay 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 alrededor de la imagen de una persona real. Este es el tipo de referencia utilizada para la generación de video consistente en rostros 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 verificación de vivacidad a través de un flujo web alojado. H5 se refiere a 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 crear 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 proporcionada por el cliente? → Trátela 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 de Seedance 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. Eso 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 a una llamada de generación, TokenLab maneja la importación y preparación detrás de escena. No necesita llamar 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. Las imágenes de referencia más grandes o complejas pueden tardar más en procesarse 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 mostrar al usuario final. Consulte los IDs de activos devueltos, espere el estado ACTIVE y luego proceda con la generación usando esos IDs.

En nuestro pipeline, tratamos este estado como un retroceso de límite de tasa: esperado, transitorio y manejado en el código en lugar de reportado como un error orientado al usuario. Recomendamos un pequeño bucle de reintento, no solo un intento/captura único.

Uso de la biblioteca de materiales de Seedance 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 de crear video.

El flujo de trabajo principal se ve así:

1. Decida si la referencia es de una persona real o no. Elija liveness_face (con verificación) o aigc_avatar en consecuencia.
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 dejando 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 vuelva a intentar 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 de Seedance actual 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. Una llamada de generación construida sobre un activo de material reutilizado puede necesitar detenerse a mitad de la ejecución. Eso puede suceder por control de costos, un brief creativo cambiado o un prompt incorrecto. Vea nuestra pieza complementaria sobre la cancelación de tareas de 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 un prototipo, comience con materiales aigc_avatar. La ruta de creación es más sencilla y no hay 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 de primera clase de su onboarding, 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. De esa manera, no estará volviendo a derivar qué activo se asigna a qué personaje o producto.
• Revise las referencias de la API de activo de material y grupo de activos de material directamente. La documentación describe la estructura 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.

El panel de control de activos de Seedance muestra el estado, el tipo de biblioteca y las relaciones de grupo de los activos que ya ha creado.

Las tarifas actuales en nuestra descripción general de precios de la API de video AI 2026 le ayudan a 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 control de TokenLab.

Preguntas frecuentes

¿En qué se diferencian los activos de material y los grupos de materiales?

Un activo de material es un objeto de referencia reutilizable único: una imagen de avatar, un rostro verificado por vivacidad, un clip de video de referencia. Su id se convierte en material_asset_id una vez que está ACTIVE. Un grupo de materiales es un contenedor identificado por group_id. Los grupos organizan los activos relacionados y son necesarios para los flujos de trabajo de liveness_face. En resumen: group_id organiza; material_asset_id genera.

¿Por qué una llamada de generación devuelve 409 seedance_material_preparing?

La preparación automática de materiales, activada por campos de imagen compatibles como image_url o start_image, puede tardar más de 60 segundos. Cuando eso sucede, la API devuelve 409 seedance_material_preparing con auto_material_asset_ids. Consulte esos IDs, espere a ACTIVE y vuelva a intentar la generación. Indica un estado transitorio en progreso, no un fallo.

¿Las referencias de personas reales siempre necesitan verificación?

Sí. Use el tipo liveness_face y su flujo de verificación siempre que la referencia involucre el rostro o la imagen de una persona real identificable. El flujo requiere la creación de una sesión, una verificación de vivacidad 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, usan aigc_avatar y no requieren este camino.

¿Puedo reutilizar un activo de material en múltiples trabajos de video de Seedance?

Sí, una vez que el activo alcanza el estado ACTIVE. Use su id como material_asset_id o dentro de material_asset_ids en una llamada create-video. Reutilice el mismo ID de activo en futuras llamadas de generación en lugar de volver a cargar la referencia. Si necesita detener un trabajo en curso, consulte la cancelación de tareas de Seedance.

Fuentes y frescura

• Guía de modelos de video de Seedance — https://docs.tokenlab.sh/guides/seedance-2-video — observado el 09-07-2026
• Crear activo de material de 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 de 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 control de activos de Seedance de TokenLab — /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 de control a partir de la fecha observada. El sistema de materiales Seedance de TokenLab está bajo desarrollo activo: confirme los nombres de los parámetros actuales, los valores de estado y el soporte específico del modelo en los documentos vinculados antes de finalizar el código de integración de producción.

Si está creando un pipeline de video que depende de referencias estables y reutilizables, comience con la guía de modelos de video de Seedance. 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.