ビデオと素材

Create Visual Validation Session

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)。言語はリクエストボディのフィールドではありません。
  3. H5フローが完了すると、ブラウザは Result.CallbackURL を開きます。コールバッククエリには bytedToken、resultCode、algorithmBaseRespCode、reqMeasureInfoValue、および verify_type が含まれる場合があります。
  4. Result.GroupId が返されるまで、保存した BytedToken を使用して ビジュアル確認結果の取得 をポーリングします。

BytedToken は30分間有効で、認証された組織と ProjectName にスコープされます。H5リンクは1回の認証完了をサポートしており、使用後は無効になります。

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 を返します。

エラー

エラーは同じトップレベルのエンベロープを使用します。TokenLabの他の /v1 APIのフィールドを期待するのではなく、ResponseMetadata.Error.Code と ResponseMetadata.Error.Message を読み取ってください。

ステータスコード原因
400InvalidParameterCallbackURL が欠落または無効(認証情報を含まないパブリックなHTTPS URLである必要があります)、Idempotency-Key が無効、または不明なフィールド
400InvalidVersionVersion が 2024-01-01 ではない
405MethodNotAllowedこのアクションは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キー認証。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キーおよび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