Video & Materialien

Visuelle Validierungssitzung erstellen

Erstellt eine Volc-kompatible visuelle Validierungssitzung für echte Personen.

POST
/api/v3

Erstellen Sie die visuelle Validierungssitzung für echte Personen, bevor Sie wiederverwendbare liveness_face-Materialien hochladen. TokenLab verwendet das Volc Action API-Format und die TokenLab Bearer-Authentifizierung.

Verwenden Sie dieselbe authentifizierte Organisation, denselben Benutzer und denselben groß-/kleinschreibungssensitiven ProjectName, mit dem die Sitzung erstellt wurde.

Öffnen Sie Result.H5Link unmittelbar nach der Erstellung der Sitzung. Der anfängliche Start kann vor dem 30-minütigen BytedToken ablaufen; zögern Sie das Öffnen nicht hinaus.

Endpunkt und Authentifizierung

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-Signierung wird nicht akzeptiert. CallbackURL ist erforderlich und muss eine öffentliche HTTPS-URL sein. ProjectName ist optional und standardmäßig auf default gesetzt.

Ablauf

  1. Speichern Sie Result.BytedToken und öffnen Sie Result.H5Link für die zu verifizierende Person.
  2. Um die H5-Sprache auszuwählen, hängen Sie lng an den H5Link an, zum Beispiel &lng=en. Die Sprache ist kein Feld im Request-Body.
  3. Nachdem der H5-Ablauf abgeschlossen ist, öffnet der Browser die Result.CallbackURL. Der Callback-Query kann bytedToken, resultCode, algorithmBaseRespCode, reqMeasureInfoValue und verify_type enthalten.
  4. Pollen Sie Visuelles Verifizierungsergebnis abrufen mit dem gespeicherten BytedToken, bis Result.GroupId zurückgegeben wird.

BytedToken ist 30 Minuten lang gültig und auf die authentifizierte Organisation sowie den ProjectName beschränkt. Der H5-Link unterstützt eine abgeschlossene Authentifizierung und wird nach der Verwendung ungültig.

Behandeln Sie Result.H5Link als undurchsichtige Browser-URL: Öffnen Sie sie als Top-Level-Seite und parsen, dekodieren, schreiben oder betten Sie sie nicht um. TokenLab verwaltet die Browser-Übergabe und die Callback-Brücke.

Beispiel-Request

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

Beispiel-Antwort

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

Sicherer Retry

Senden Sie einen optionalen Idempotency-Key-Header (1–255 Zeichen), damit eine verlorene Antwort wiederhergestellt werden kann. Ein Retry mit demselben Schlüssel, API-Key, CallbackURL und ProjectName gibt dasselbe BytedToken und denselben H5Link zurück. Derselbe Schlüssel mit einem anderen Request gibt 409 IdempotencyConflict zurück. Während der erste Request noch erstellt wird, lautet die Antwort 409 RequestInProgress mit Retry-After: 2. Ein ungültiger Schlüssel gibt 400 InvalidParameter zurück.

Fehler

Fehler verwenden denselben Top-Level-Envelope. Lesen Sie ResponseMetadata.Error.Code und ResponseMetadata.Error.Message, anstatt die Felder aus anderen /v1-APIs von TokenLab zu erwarten.

StatusCodeUrsache
400InvalidParameterFehlende oder ungültige CallbackURL (muss eine öffentliche HTTPS-URL ohne Anmeldedaten sein), ungültiger Idempotency-Key oder ein unbekanntes Feld
400InvalidVersionVersion ist nicht 2024-01-01
405MethodNotAllowedDie Action akzeptiert nur POST
409IdempotencyConflict, RequestInProgressSiehe Sicherer Retry
503ServiceUnavailableDie Validierung für echte Personen ist für dieses Konto nicht verfügbar oder fehlgeschlagen; versuchen Sie es später erneut
curl -X POST "https://example.com/api/v3" \  -H "Content-Type: application/json" \  -d '{    "CallbackURL": "http://example.com"  }'
{  "id": "string"}

Autorisierung

BearerAuth
AuthorizationBearer <token>

API-Key-Authentifizierung. Erstellen oder verwalten Sie API-Keys unter Dashboard > API > API Keys.

Ort: header

Abfrageparameter

Action?string

Zulässige Werte

  • "CreateContentsGenerationsTasks"
  • "GetContentsGenerationsTask"
  • "ListContentsGenerationsTasks"
  • "DeleteContentsGenerationsTasks"
  • "CreateVisualValidateSession"
  • "GetVisualValidateResult"
  • "CreateAssetGroup"
  • "ListAssetGroups"
  • "GetAssetGroup"
  • "UpdateAssetGroup"
  • "DeleteAssetGroup"
  • "CreateAsset"
  • "ListAssets"
  • "GetAsset"
  • "UpdateAsset"
  • "DeleteAsset"
Version?string
Standard"2024-01-01"

Header

X-TokenLab-Delivery-Policy?string

Zustellungsrichtlinie pro Anfrage. Überschreibt die API-Key- und Workspace-Standardeinstellungen. Versucht automatisch zuerst TokenLab Verified und kann vor der Ausgabe, der Annahme der Anfrage oder der Erstellung persistenter Ressourcen einmalig auf Official umstellen.

Zulässige Werte

  • "auto"
  • "verified"
  • "official"

Anfragekörper

application/json

Antwort

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json