視頻與素材
建立視覺驗證工作階段
建立一個與 Volc 相容的真人視覺驗證工作階段。
在上傳可重複使用的 liveness_face 素材之前,請先建立真人視覺驗證工作階段。TokenLab 使用 Volc Action API 格式以及 TokenLab Bearer 驗證。
請使用建立該工作階段時所使用的相同已驗證組織、使用者以及區分大小寫的 ProjectName。
在建立工作階段後,請立即開啟 Result.H5Link。其初始啟動時間可能會早於 30 分鐘的 BytedToken 過期時間;請勿延遲開啟。
端點與驗證
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。
流程
- 儲存
Result.BytedToken並為正在進行驗證的人員開啟Result.H5Link。 - 若要選擇 H5 語言,請在
H5Link後方附加lng,例如&lng=en。語言並非請求主體 (request-body) 的欄位。 - H5 流程結束後,瀏覽器會開啟
Result.CallbackURL。回呼查詢參數可能包含bytedToken、resultCode、algorithmBaseRespCode、reqMeasureInfoValue以及verify_type。 - 使用儲存的
BytedToken輪詢 取得視覺驗證結果,直到回傳Result.GroupId為止。
BytedToken 的有效期為 30 分鐘,且僅限於已驗證的組織與 ProjectName 使用。H5 連結僅支援一次完成的驗證,使用後即失效。
請將 Result.H5Link 視為不透明的瀏覽器 URL:請將其作為頂層頁面開啟,切勿解析、解碼、重寫或嵌入該連結。TokenLab 負責處理瀏覽器交接與回呼橋接。
請求範例
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"
}
}安全重試
您可以傳送選填的 Idempotency-Key 標頭(1–255 個字元),以便在回應遺失時進行復原。使用相同的金鑰、API 金鑰、CallbackURL 與 ProjectName 進行重試,將會回傳相同的 BytedToken 與 H5Link。若使用相同的金鑰但請求內容不同,則會回傳 409 IdempotencyConflict。若第一個請求仍在建立中,回應將為 409 RequestInProgress 並附帶 Retry-After: 2。無效的金鑰會回傳 400 InvalidParameter。
錯誤
錯誤使用相同的頂層封裝。請讀取 ResponseMetadata.Error.Code 與 ResponseMetadata.Error.Message,而非預期 TokenLab 其他 /v1 API 中的欄位。
| 狀態 | 代碼 | 原因 |
|---|---|---|
400 | InvalidParameter | 缺少或無效的 CallbackURL(必須是無憑證的公開 HTTPS URL)、無效的 Idempotency-Key,或包含未知欄位 |
400 | InvalidVersion | Version 不是 2024-01-01 |
405 | MethodNotAllowed | 此 Action 僅接受 POST |
409 | IdempotencyConflict, RequestInProgress | 請參閱「安全重試」章節 |
503 | ServiceUnavailable | 此帳戶無法使用真人驗證或驗證失敗;請稍後再試 |
curl -X POST "https://example.com/api/v3" \ -H "Content-Type: application/json" \ -d '{ "CallbackURL": "http://example.com" }'{ "id": "string"}授權
BearerAuth API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。
位置: header
查詢參數
可選值
- "CreateContentsGenerationsTasks"
- "GetContentsGenerationsTask"
- "ListContentsGenerationsTasks"
- "DeleteContentsGenerationsTasks"
- "CreateVisualValidateSession"
- "GetVisualValidateResult"
- "CreateAssetGroup"
- "ListAssetGroups"
- "GetAssetGroup"
- "UpdateAssetGroup"
- "DeleteAssetGroup"
- "CreateAsset"
- "ListAssets"
- "GetAsset"
- "UpdateAsset"
- "DeleteAsset"
"2024-01-01"請求標頭
單次請求傳遞策略。會覆寫 API key 與 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