TokenLab

視頻與素材

建立視覺驗證工作階段

建立一個與 Volc 相容的真人視覺驗證工作階段。

POST
/api/v3

在上傳可重複使用的 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。

流程

  1. 儲存 Result.BytedToken 並為正在進行驗證的人員開啟 Result.H5Link。
  2. 若要選擇 H5 語言,請在 H5Link 後方附加 lng,例如 &lng=en。語言並非請求主體 (request-body) 的欄位。
  3. H5 流程結束後,瀏覽器會開啟 Result.CallbackURL。回呼查詢參數可能包含 bytedToken、resultCode、algorithmBaseRespCode、reqMeasureInfoValue 以及 verify_type。
  4. 使用儲存的 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 中的欄位。

狀態代碼原因
400InvalidParameter缺少或無效的 CallbackURL(必須是無憑證的公開 HTTPS URL)、無效的 Idempotency-Key,或包含未知欄位
400InvalidVersionVersion 不是 2024-01-01
405MethodNotAllowed此 Action 僅接受 POST
409IdempotencyConflict, RequestInProgress請參閱「安全重試」章節
503ServiceUnavailable此帳戶無法使用真人驗證或驗證失敗;請稍後再試
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 金鑰。

位置: 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 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