Video y recursos

Crear sesión de validación visual

Crea una sesión de validación visual de persona real compatible con Volc.

POST
/api/v3

Cree la sesión de validación visual de persona real antes de cargar materiales liveness_face reutilizables. TokenLab utiliza el formato de API de acción de Volc y la autenticación Bearer de TokenLab.

Utilice la misma organización autenticada, el mismo usuario y el mismo ProjectName (sensible a mayúsculas y minúsculas) que creó la sesión.

Abra Result.H5Link inmediatamente después de crear la sesión. Su lanzamiento inicial puede expirar antes del BytedToken de 30 minutos; no retrase su apertura.

Endpoint y autenticación

POST https://api.tokenlab.sh/api/v3?Action=CreateVisualValidateSession&Version=2024-01-01
Authorization: Bearer <TOKENLAB_API_KEY>
Content-Type: application/json

La firma AK/SK de Volc no es aceptada. CallbackURL es obligatorio y debe ser una URL HTTPS pública. ProjectName es opcional y su valor predeterminado es default.

Flujo

  1. Guarde Result.BytedToken y abra Result.H5Link para la persona que se está verificando.
  2. Para seleccionar el idioma de H5, añada lng a H5Link, por ejemplo &lng=en. El idioma no es un campo del cuerpo de la solicitud.
  3. Una vez finalizado el flujo H5, el navegador abre Result.CallbackURL. La consulta de callback puede contener bytedToken, resultCode, algorithmBaseRespCode, reqMeasureInfoValue y verify_type.
  4. Realice peticiones (polling) a Obtener resultado de validación visual con el BytedToken guardado hasta que se devuelva Result.GroupId.

BytedToken es válido durante 30 minutos y está limitado a la organización autenticada y al ProjectName. El enlace H5 admite una autenticación completada y deja de ser válido después de su uso.

Trate Result.H5Link como una URL de navegador opaca: ábrala como una página de nivel superior y no la analice, decodifique, reescriba ni incruste. TokenLab gestiona el traspaso del navegador y el puente de callback.

Ejemplo de solicitud

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

Ejemplo de respuesta

{
  "ResponseMetadata": {
    "RequestId": "req_abc123",
    "Action": "CreateVisualValidateSession",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "BytedToken": "ZXhhbXBsZS10b2tlbg",
    "H5Link": "https://api.tokenlab.sh/api/v3/visual-validation/sessions/svv_example/h5?Version=2024-01-01",
    "CallbackURL": "https://yourapp.example.com/seedance/callback"
  }
}

Reintento seguro

Envíe un encabezado opcional Idempotency-Key (de 1 a 255 caracteres) para que se pueda recuperar una respuesta perdida. Un reintento con la misma clave, API key, CallbackURL y ProjectName devuelve el mismo BytedToken y H5Link. La misma clave con una solicitud diferente devuelve 409 IdempotencyConflict. Mientras la primera solicitud aún se está creando, la respuesta es 409 RequestInProgress con Retry-After: 2. Una clave no válida devuelve 400 InvalidParameter.

Errores

Los errores utilizan el mismo sobre de nivel superior. Lea ResponseMetadata.Error.Code y ResponseMetadata.Error.Message en lugar de esperar los campos de otras API /v1 de TokenLab.

EstadoCódigoCausa
400InvalidParameterCallbackURL faltante o no válido (debe ser una URL HTTPS pública sin credenciales), Idempotency-Key no válido o un campo desconocido
400InvalidVersionVersion no es 2024-01-01
405MethodNotAllowedLa acción solo acepta POST
409IdempotencyConflict, RequestInProgressVer Reintento seguro
503ServiceUnavailableLa validación de persona real no está disponible para esta cuenta o falló; inténtelo de nuevo más tarde
curl -X POST "https://example.com/api/v3" \  -H "Content-Type: application/json" \  -d '{    "CallbackURL": "http://example.com"  }'
{  "id": "string"}

Autorización

BearerAuth
AuthorizationBearer <token>

Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.

Ubicación: header

Parámetros de consulta

Action?string

Valores permitidos

  • "CreateContentsGenerationsTasks"
  • "GetContentsGenerationsTask"
  • "ListContentsGenerationsTasks"
  • "DeleteContentsGenerationsTasks"
  • "CreateVisualValidateSession"
  • "GetVisualValidateResult"
  • "CreateAssetGroup"
  • "ListAssetGroups"
  • "GetAssetGroup"
  • "UpdateAssetGroup"
  • "DeleteAssetGroup"
  • "CreateAsset"
  • "ListAssets"
  • "GetAsset"
  • "UpdateAsset"
  • "DeleteAsset"
Version?string
predeterminado"2024-01-01"

Encabezados

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitud. Sustituye los valores predeterminados de la API key y del Workspace. Auto intenta primero con TokenLab Verified y puede cambiar una vez a Official solo antes de la salida, la aceptación de la solicitud o la creación de recursos persistentes.

Valores permitidos

  • "auto"
  • "verified"
  • "official"

Cuerpo de la solicitud

application/json

Respuesta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json