Vídeo e materiais

Criar Sessão de Validação Visual

Cria uma sessão de validação visual de pessoa real compatível com Volc.

POST
/api/v3

Crie a sessão de validação visual de pessoa real antes de enviar materiais liveness_face reutilizáveis. O TokenLab utiliza o formato da Volc Action API e autenticação Bearer do TokenLab.

Utilize a mesma organização autenticada, usuário e ProjectName (diferencia maiúsculas de minúsculas) que criou a sessão.

Abra o Result.H5Link imediatamente após criar a sessão. Sua inicialização pode expirar antes do BytedToken de 30 minutos; não atrase a abertura.

Endpoint e Autenticação

POST https://api.tokenlab.sh/api/v3?Action=CreateVisualValidateSession&Version=2024-01-01
Authorization: Bearer <TOKENLAB_API_KEY>
Content-Type: application/json

A assinatura Volc AK/SK não é aceita. CallbackURL é obrigatório e deve ser uma URL HTTPS pública. ProjectName é opcional e o padrão é default.

Fluxo

  1. Salve o Result.BytedToken e abra o Result.H5Link para a pessoa que está sendo verificada.
  2. Para selecionar o idioma do H5, adicione lng ao H5Link, por exemplo &lng=en. O idioma não é um campo do corpo da requisição.
  3. Após o término do fluxo H5, o navegador abre a Result.CallbackURL. A query do callback pode conter bytedToken, resultCode, algorithmBaseRespCode, reqMeasureInfoValue e verify_type.
  4. Realize o polling em Obter resultado da validação visual com o BytedToken salvo até que o Result.GroupId seja retornado.

O BytedToken é válido por 30 minutos e está vinculado à organização autenticada e ao ProjectName. O link H5 suporta uma autenticação concluída e torna-se inválido após o uso.

Trate o Result.H5Link como uma URL de navegador opaca: abra-a como uma página de nível superior e não analise, decodifique, reescreva ou incorpore (embed) a mesma. O TokenLab é responsável pela transição do navegador e pela ponte de callback.

Exemplo de Requisição

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

Exemplo de Resposta

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

Tentativa Segura (Retry)

Envie um cabeçalho opcional Idempotency-Key (1–255 caracteres) para que uma resposta perdida possa ser recuperada. Uma nova tentativa com a mesma chave, chave de API, CallbackURL e ProjectName retorna o mesmo BytedToken e H5Link. A mesma chave com uma requisição diferente retorna 409 IdempotencyConflict. Enquanto a primeira requisição ainda está sendo criada, a resposta é 409 RequestInProgress com Retry-After: 2. Uma chave inválida retorna 400 InvalidParameter.

Erros

Os erros utilizam o mesmo envelope de nível superior. Leia ResponseMetadata.Error.Code e ResponseMetadata.Error.Message em vez de esperar os campos das outras APIs /v1 do TokenLab.

StatusCódigoCausa
400InvalidParameterCallbackURL ausente ou inválida (deve ser uma URL HTTPS pública sem credenciais), Idempotency-Key inválida ou um campo desconhecido
400InvalidVersionVersion não é 2024-01-01
405MethodNotAllowedA Action aceita apenas POST
409IdempotencyConflict, RequestInProgressVeja Tentativa Segura (Retry)
503ServiceUnavailableA validação de pessoa real está indisponível para esta conta ou falhou; tente novamente mais tarde
curl -X POST "https://example.com/api/v3" \  -H "Content-Type: application/json" \  -d '{    "CallbackURL": "http://example.com"  }'
{  "id": "string"}

Autorização

BearerAuth
AuthorizationBearer <token>

Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.

Local: header

Parâmetros de consulta

Action?string

Valores permitidos

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

Cabeçalhos

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitação. Substitui os padrões da API key e do Workspace. Tenta automaticamente o TokenLab Verified primeiro e pode alternar uma vez para Official apenas antes da saída, aceitação da solicitação ou criação de recurso persistente.

Valores permitidos

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

Corpo da requisição

application/json

Resposta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json