TokenLab
获取 API 密钥
文档API 参考集成

视频与素材

创建视觉验证会话

创建真人视觉验证会话。

POST
/api/v3

上传可复用的 liveness_face 素材需要完成人脸验证。该接口兼容火山引擎 Action API 的请求格式，使用 TokenLab Bearer 认证。

查询时须使用创建会话的同一组织、用户，以及相同且区分大小写的 ProjectName。

创建会话后请立即打开 Result.H5Link。H5 的首次打开期限可能早于 BytedToken 的 30 分钟有效期，不要延迟打开。

接口与认证

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

不接受火山引擎 AK/SK 签名。CallbackURL 为必填项，且必须是公开的 HTTPS URL。ProjectName 可选，默认值为 default。

完成验证

  1. 保存 Result.BytedToken，并为待验证人员打开 Result.H5Link。
  2. 如需指定 H5 语言，请在 H5Link 后追加 lng，例如 &lng=en。语言不是请求体字段。
  3. 验证完成后，浏览器会打开 Result.CallbackURL。回调查询参数可能包含 bytedToken、resultCode、algorithmBaseRespCode、reqMeasureInfoValue 和 verify_type。
  4. 使用保存的 BytedToken 查询 视觉验证结果，直到返回 Result.GroupId。

BytedToken 的有效期为 30 分钟，并与当前工作区和 ProjectName 绑定。H5 链接只能完成一次验证，使用后即失效。

请直接在浏览器顶层页面打开 Result.H5Link，不要解析、改写或嵌入该地址。

请求示例

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

响应示例

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

失败时，错误码和错误信息分别位于 ResponseMetadata.Error.Code 和 ResponseMetadata.Error.Message。

curl -X POST "https://example.com/api/v3" \  -H "Content-Type: application/json" \  -d '{    "CallbackURL": "http://example.com"  }'
{  "id": "string"}

授权

BearerAuth
AuthorizationBearer <token>

API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。

位置: header

查询参数

Action?string

可选值

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

请求头

X-TokenLab-Delivery-Policy?string

单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified，并在输出、请求接受或持久资源创建之前，可能会切换一次至仅限 Official。

可选值

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

请求体

application/json

响应

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

获取视频状态

上一页

获取视觉验证结果

下一页