Guías de medios

Materiales de Seedance y verificación de personas reales

Reutilice imágenes, videos, audio o una persona verificada en Seedance

Los materiales de Seedance le permiten reutilizar un archivo de imagen, video o audio sin tener que importarlo para cada generación. Las referencias a una persona real requieren consentimiento y verificación visual; las personas virtuales, los productos y los estilos no lo requieren.

Elija un tipo de material

Lo que desea reutilizarQué hacer
Una imagen usada una vezEnvíe su URL en un campo de imagen compatible; esto no crea un ID de material reutilizable
Reutilizar una persona virtual, producto o estiloCree un grupo aigc_avatar, cree un activo, espere a que esté ACTIVE y luego use el ID del activo
Reutilizar una persona realComplete la validación visual, reciba su GroupId, cree un activo en ese grupo, espere a que esté ACTIVE y luego use el ID del activo
Migrar un cliente de material existente de VolcengineMantenga la estructura de la solicitud de Action y utilice la referencia de material compatible con Volc

Grupos y materiales

ElementoCampo RESTCampo ActionQué significa
Grupo de materialesgroup_idGroupIdMantiene los materiales relacionados juntos
MaterialidIdUn archivo de imagen, video o audio importado; use este ID después de que esté activo
Grupo de avatar virtuallibrary_type: "aigc_avatar"GroupType: "AIGC"No requiere verificación de persona real
Grupo de persona reallibrary_type: "liveness_face"GroupType: "LivenessFace"Creado solo mediante un flujo de validación visual exitoso
Nombre del proyectoproject_nameProjectNameMantiene separados los materiales de diferentes proyectos; el valor predeterminado es default

Mantenga los IDs de grupo y los IDs de activo separados. Un grupo organiza las cargas; un ID de activo es la referencia utilizada por la generación de video. Los IDs públicos tienen un formato como group-20260720123456-vrt01 y asset-20260720123457-def45.

Retención de materiales

TokenLab conserva cada activo de material hasta que usted elimine el activo o su grupo. No se eliminan por inactividad.

  • Si un activo necesita ser preparado nuevamente cuando lo utiliza, la primera generación puede tardar un poco más. Si aún no está listo, la solicitud devuelve 409 seedance_material_preparing; vuelva a intentarlo en breve.
  • Eliminar un activo o grupo es permanente y no se puede deshacer.

URLs de imágenes y materiales reutilizables

Envíe URLs HTTP(S) públicas o URLs de datos compatibles en los campos de imagen aceptados por el modelo seleccionado. Estas entradas siguen la ruta de medios normal y no crean automáticamente IDs de material reutilizables.

Para materiales reutilizables, cree un activo a través de la API de materiales, espere a que esté ACTIVE y luego use material_asset_id, material_asset_ids o asset://<id> en un campo de medios compatible. Mantenga el rol previsto de primer fotograma, último fotograma o imagen de referencia.

Cuando un material explícito aún se está preparando, POST /v1/videos/generations devuelve 409 seedance_material_preparing con inactive_asset_ids. Realice sondeos (polling) de esos activos hasta que estén ACTIVE, luego vuelva a intentarlo con los mismos IDs de material. Si un activo está FAILED, inspeccione el error_message y corríjalo o vuelva a importarlo antes de reintentar. Una solicitud de generación que utiliza un activo fallido devuelve 422 seedance_material_failed con failed_asset_ids.

Materiales de avatar virtual

Utilice Crear grupo de activos de material para crear un grupo aigc_avatar. Para la creación de activos REST, group_id es opcional solo cuando project_name es default; TokenLab entonces utiliza o crea el grupo de avatar virtual predeterminado de la organización. Un project_name que no sea el predeterminado, y cada activo de persona real, requiere un group_id.

Después de que exista un grupo, adminístrelo con:

Eliminar un grupo también elimina los materiales de TokenLab que contiene y no se puede deshacer.

Verificación de persona real

Utilice este flujo cuando su producto deba recopilar consentimiento y verificar un rostro antes de reutilizar a una persona real como referencia de Seedance.

  1. Llame a Crear sesión de validación visual con CallbackURL; guarde Result.BytedToken y abra Result.H5Link para la persona que se está verificando.
  2. Después de que el flujo H5 redirija a la devolución de llamada (callback), realice un sondeo en Obtener resultado de validación visual con el mismo BytedToken y ProjectName.
  3. Almacene el Result.GroupId devuelto. TokenLab crea y vincula el grupo LivenessFace durante este paso.
  4. Cree un activo con ese ID de grupo, luego realice un sondeo del activo hasta que esté ACTIVE.

BytedToken es válido por 30 minutos. Un cliente no puede crear un grupo LivenessFace con CreateAssetGroup; esto evita que un grupo no verificado se presente como verificado.

Abra el H5Link devuelto inmediatamente después de la creación. La validez del token no significa que la página de verificación pueda abrirse por primera vez en cualquier momento dentro de esa ventana.

Para un grupo de persona real, las cargas se verifican contra el rostro verificado. Un activo puede fallar si contiene múltiples rostros o si el rostro no coincide. Para obtener los mejores resultados, cargue una referencia de cuerpo completo de frente y un primer plano claro de frente.

Crear y preparar un activo

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

TipoEntrada compatible
Imagenjpeg, png, webp, bmp, tiff, gif, heic, heif; ≤ 30 MiB; ancho y alto [300, 6000] px; relación de aspecto [0.4, 2.5]
Videomp4, mov; ≤ 200 MiB
Audioaac, wav, mp3; ≤ 15 MiB

Estos son límites de importación de archivos. Una solicitud de importación exitosa no garantiza que la validación de medios o de persona real sea aprobada. Espere a que esté ACTIVE; si el activo pasa a FAILED, utilice error_message para corregir la fuente antes de importar nuevamente.

La ingesta de material es asíncrona. Realice un sondeo en Obtener activo de material hasta que el status sea ACTIVE. El éxito HTTP significa que la importación fue aceptada, no que el activo esté listo. Si el activo pasa a FAILED, inspeccione error_message, corrija la fuente y cree un nuevo activo.

La URL de origen solo se utiliza para la importación. TokenLab devuelve su propio ID de activo y mantiene el activo en la biblioteca de materiales de su organización hasta que usted elimine el activo o su grupo.

Usar un activo en la generación de video

Después de que un activo esté ACTIVE, elija una de estas formas al llamar a Crear video:

  • material_asset_id para una referencia de material genérica
  • material_asset_ids para múltiples referencias genéricas
  • asset://<asset-id> en image_url, start_image, end_image o reference_images cuando el rol del medio deba ser explícito

Las referencias de material cuentan para los límites de referencia de Seedance del modelo seleccionado. Si la API devuelve Seedance material asset not found or not accessible, confirme que el valor sea un ID de activo en lugar de un ID de grupo, que pertenezca a la misma organización y proyecto, que no haya sido eliminado y que esté ACTIVE.

REST o Action de Volcengine

Las integraciones nativas de TokenLab pueden seguir utilizando los endpoints REST /v1/videos/assets* en snake_case. Los clientes existentes de Volcengine pueden conservar los cuerpos en PascalCase con Acciones de material (compatibles con Volc). Ambas interfaces operan sobre los mismos datos de material con alcance de organización y proyecto.

Ejemplo REST: Activo de avatar virtual

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","project_name":"default"}'

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

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

Ejemplo de Action: Activo de persona real verificado

Primero cree y complete la validación visual:

curl 'https://api.tokenlab.sh/?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/?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken":"<BYTED_TOKEN>","ProjectName":"default"}'

Luego pase el GroupId devuelto a CreateAsset:

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"
  }'

Realice un sondeo con GetAsset hasta que su estado sea Active, luego pase el ID de activo devuelto a la generación de video. Para conocer las 10 operaciones de Action, filtros, paginación, estructuras de respuesta y errores, consulte Acciones de material (compatibles con Volc).

En esta página