ビジュアル確認セッションの作成

再利用可能な liveness_face 素材をアップロードする前に、実在人物のビジュアル確認セッションを作成します。TokenLab は Volc Action API 形式と TokenLab Bearer 認証を使用します。

セッションを作成したものと同じ認証済み組織、ユーザー、大文字と小文字を区別した ProjectName を使用してください。

セッション作成後、すぐに Result.H5Link を開いてください。H5 の初回起動期限は、30 分間有効な BytedToken より早い場合があります。

エンドポイントと認証Copy Anchor Link

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

Volc の AK/SK 署名は受け付けません。CallbackURL は必須で、公開 HTTPS URL である必要があります。ProjectName は省略でき、既定値は default です。

フローCopy Anchor Link

1. Result.BytedToken を保存し、確認対象者に Result.H5Link を開きます。
2. H5 の言語を指定するには、H5Link に lng を追加します（例: &lng=en）。言語はリクエスト本文のフィールドではありません。
3. H5 フローが完了すると、ブラウザーが Result.CallbackURL を開きます。コールバックのクエリには bytedToken、resultCode、algorithmBaseRespCode、reqMeasureInfoValue、verify_type が含まれる場合があります。
4. 保存した BytedToken で ビジュアル確認結果の取得 をポーリングし、Result.GroupId が返るまで待ちます。

BytedToken の有効期間は30分で、認証済み組織と ProjectName に紐付きます。H5リンクで完了できる認証は1回だけで、使用後は無効になります。

Result.H5Link は不透明なブラウザー URL として扱い、トップレベルページとして開いてください。解析、デコード、書き換え、埋め込みは行わないでください。ブラウザーの引き渡しと callback ブリッジは TokenLab が管理します。

リクエスト例Copy Anchor Link

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

レスポンス例Copy Anchor Link

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

エラーも同じ最上位形式を使用します。TokenLab の他の /v1 API のフィールドではなく、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"}