Materiales de Seedance y verificación de personas

Los materiales de Seedance son referencias de imagen, video o audio reutilizables dentro de una organización. Elige primero el flujo: los materiales de avatar normales y los de personas verificadas no siguen la misma ruta de creación.

Elige un flujo de materialesCopy Anchor Link

Conceptos de materialCopy Anchor Link

Los materiales de Seedance son referencias reutilizables con alcance de organización que pueden seleccionarse posteriormente durante la generación de video.

Mantenga group_id y el id del activo de material separados. group_id es para organizar las cargas; el id del activo de material es para la generación de video. Si una solicitud de video devuelve Seedance material asset not found or not accessible, confirme que ha pasado un id de activo de material, no un group_id, y que el activo pertenece a la misma organización, no ha sido eliminado y tiene status: "ACTIVE".

Conservación de materialesCopy Anchor Link

TokenLab conserva cada activo de material hasta que usted elimine el activo o su grupo. TokenLab no lo limpia por inactividad.

El proveedor upstream de Seedance puede eliminar su propia copia de trabajo de un activo tras 30 días sin uso. Esto no elimina su activo ni cambia su ID: la próxima vez que lo use en una solicitud de generación, TokenLab prepara automáticamente una nueva copia upstream a partir del original almacenado.

• La primera generación tras una limpieza puede tardar un poco más mientras se prepara la nueva copia. Si aún no está lista, la solicitud devuelve seedance_material_preparing; vuelva a intentarlo en breve.
• Eliminar un activo o un grupo es permanente y no se puede deshacer.

URL de imágenes y recursos reutilizablesCopy Anchor Link

Envía URL HTTP(S) públicas o data URL admitidas en los campos de imagen del modelo elegido. Se procesan como entradas multimedia normales y no crean automáticamente ID de recursos reutilizables.

Para reutilizar un recurso, créalo mediante la API de materiales, espera a ACTIVE y usa material_asset_id, material_asset_ids o asset://<id> en un campo multimedia admitido. Conserva su función de primer fotograma, último fotograma o imagen de referencia.

Si un recurso indicado explícitamente sigue preparándose, POST /v1/videos/generations devuelve 409 seedance_material_preparing con inactive_asset_ids. Consulta esos recursos hasta ACTIVE y reintenta con los mismos ID. Si aparece FAILED, revisa error_message y corrige o vuelve a importar el recurso antes de reintentar.

Verificación de material de persona realCopy Anchor Link

Utilice la verificación de material de persona real cuando su producto requiera consentimiento y verificación facial antes de que una persona real pueda ser utilizada como referencia reutilizable de Seedance.

1. Llame a Crear sesión de validación visual con CallbackURL y guarde el Result.BytedToken devuelto.
2. Abra Result.H5Link para la persona que se verificará. Añada lng al enlace H5 si necesita un idioma específico.
3. Al finalizar el flujo H5, el navegador abre Result.CallbackURL con nombres de consulta oficiales como bytedToken y resultCode.
4. Consulte Obtener resultado de validación visual con BytedToken hasta que se devuelva Result.GroupId.
5. Guarde GroupId y úselo como group_id al crear materiales liveness_face.

BytedToken es válido durante 30 minutos. Use el mismo ProjectName en ambas solicitudes Action. La autenticación usa Authorization: Bearer <TOKENLAB_API_KEY>; no se aceptan firmas AK/SK de Volc.

Abre el H5Link devuelto inmediatamente después de crearlo. La validez del token no garantiza que puedas abrir la página de verificación por primera vez en cualquier momento de ese periodo.

Opcional: utilice la consola de prueba para verificar su flujo de solicitud y callback, inspeccionar grupos de materiales y revisar el historial de verificación. Su integración de producción debe llamar a las APIs directamente.

Creación de grupos de materialesCopy Anchor Link

Utilice Crear grupo de activos de material para grupos de tipo aigc_avatar. Los nuevos grupos de personas reales se crean a través del flujo de verificación para que la persona verificada y el grupo de material permanezcan vinculados.

Utilice Listar grupos de activos de material, Obtener grupo de activos de material, Actualizar grupo de activos de material y Eliminar grupo de activos de material para gestionar los grupos una vez creados.

Eliminar un grupo de material también elimina los materiales de TokenLab contenidos en él y no se puede deshacer. Si la biblioteca de materiales de TokenLab no puede completar la eliminación porque el estado de autorización actual no lo permite, TokenLab devuelve un error neutral de biblioteca de materiales.

Carga de materialesCopy Anchor Link

Utilice Crear activo de material para importar una URL de origen accesible públicamente a la vez.

Para aigc_avatar, group_id es opcional; TokenLab utiliza o crea el grupo de avatar virtual predeterminado de la organización. Para liveness_face, group_id es obligatorio y debe ser el grupo devuelto por Obtener resultado de validación visual.

La tabla indica límites de importación. Una solicitud aceptada no garantiza que se supere la validación del medio o de la persona. Espera ACTIVE; ante FAILED, corrige el origen según error_message antes de importarlo de nuevo.

La ingesta de material es asíncrona. Realice sondeos (polling) a Obtener activo de material hasta que el status sea ACTIVE. Una respuesta HTTP exitosa solo significa que la solicitud fue aceptada; lea siempre el estado comercial. Si el estado es FAILED, inspeccione error_message, corrija el material de origen y cree un nuevo activo.

En las solicitudes de creación de material, asset_url es solo el origen de importación. TokenLab devuelve un id de activo de material; use ese id para generar videos en lugar de reutilizar la URL original.

TokenLab conserva los activos de material en la biblioteca de su organización hasta que elimine el activo o su grupo de material. La copia upstream se vuelve a crear automáticamente si se limpia; consulte la sección de conservación anterior.

Para grupos de material de persona real, un grupo se asigna a una persona real. Las cargas se verifican contra el rostro verificado. Los activos con múltiples rostros o un rostro que no coincida con la persona verificada pueden fallar. Para obtener mejores resultados, cargue tanto una imagen de referencia de cuerpo completo como un primer plano frontal donde el rostro sea claro.

Uso de materiales en la generación de videoCopy Anchor Link

Después de que un activo esté ACTIVE, pase el id del activo de TokenLab devuelto como material_asset_id, o inclúyalo en material_asset_ids, al llamar a Crear video. Los activos de material cuentan para los límites de referencia de Seedance.

REST o Action de VolcengineCopy Anchor Link

Una integración nativa de TokenLab puede seguir usando la API REST snake_case /v1/videos/assets*. Un cliente Volcengine existente puede conservar cuerpos PascalCase con las Actions de materiales compatibles con Volcengine. Ambas interfaces operan sobre los mismos datos delimitados por organización y proyecto.

Ejemplos de APICopy Anchor Link

Cree un grupo de avatar virtual, cargue una imagen, realice sondeos hasta que esté activo y luego use el ID del activo de material en una solicitud de video.

curl https://api.tokenlab.sh/v1/videos/assets/groups \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_name":"Product references"}'

curl https://api.tokenlab.sh/v1/videos/assets \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_id":"group-20260720123456-abc12","asset_url":"https://example.com/reference.png","asset_type":"Image"}'

curl https://api.tokenlab.sh/v1/videos/assets/asset-20260720123457-def45 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

Para un grupo de materiales de persona real, cree una sesión de validación visual y obtenga el resultado antes de cargar materiales.

curl 'https://api.tokenlab.sh/api/v3?Action=CreateVisualValidateSession&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"CallbackURL":"https://yourapp.example.com/seedance/callback","ProjectName":"default"}'

curl 'https://api.tokenlab.sh/api/v3?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken":"ZXhhbXBsZS10b2tlbg","ProjectName":"default"}'

Flujo Action completo para una persona realCopy Anchor Link

Pasa a CreateAsset el GroupId devuelto por el resultado de verificación.

curl 'https://api.tokenlab.sh/?Action=CreateAsset&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId":"group-20260720123456-real1",
    "URL":"https://example.com/person-front.png",
    "Name":"Verified front view",
    "AssetType":"Image",
    "ProjectName":"default"
  }'

Consulta GetAsset hasta que el estado sea Active y usa el ID del material devuelto en la generación de video.