建立視覺驗證會話

上傳可重複使用的 liveness_face 素材前，請先建立真人視覺驗證會話。TokenLab 採用火山引擎 Action API 的請求格式，並使用 TokenLab Bearer 驗證。

查詢時須使用建立會話的同一組織、使用者，以及相同且區分大小寫的 ProjectName。

建立會話後請立即開啟 Result.H5Link。H5 的首次開啟期限可能早於 BytedToken 的 30 分鐘有效期，請勿延遲開啟。

端點與驗證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

不接受火山引擎 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 連結只允許完成一次驗證，使用後即失效。

請將 Result.H5Link 視為不透明的瀏覽器 URL：以頂層頁面開啟，不要解析、解碼、改寫或嵌入。瀏覽器交接與回呼橋接由 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"
  }
}

錯誤也使用相同的頂層結構。請讀取 ResponseMetadata.Error.Code 與 ResponseMetadata.Error.Message，不要預期 TokenLab 其他 /v1 API 的錯誤欄位。

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

{  "id": "string"}