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.
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/jsonA 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
- Salve o
Result.BytedTokene abra oResult.H5Linkpara a pessoa que está sendo verificada. - Para selecionar o idioma do H5, adicione
lngaoH5Link, por exemplo&lng=en. O idioma não é um campo do corpo da requisição. - Após o término do fluxo H5, o navegador abre a
Result.CallbackURL. A query do callback pode conterbytedToken,resultCode,algorithmBaseRespCode,reqMeasureInfoValueeverify_type. - Realize o polling em Obter resultado da validação visual com o
BytedTokensalvo até que oResult.GroupIdseja 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.
| Status | Código | Causa |
|---|---|---|
400 | InvalidParameter | CallbackURL ausente ou inválida (deve ser uma URL HTTPS pública sem credenciais), Idempotency-Key inválida ou um campo desconhecido |
400 | InvalidVersion | Version não é 2024-01-01 |
405 | MethodNotAllowed | A Action aceita apenas POST |
409 | IdempotencyConflict, RequestInProgress | Veja Tentativa Segura (Retry) |
503 | ServiceUnavailable | A 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 Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.
Local: header
Parâmetros de consulta
Valores permitidos
- "CreateContentsGenerationsTasks"
- "GetContentsGenerationsTask"
- "ListContentsGenerationsTasks"
- "DeleteContentsGenerationsTasks"
- "CreateVisualValidateSession"
- "GetVisualValidateResult"
- "CreateAssetGroup"
- "ListAssetGroups"
- "GetAssetGroup"
- "UpdateAssetGroup"
- "DeleteAssetGroup"
- "CreateAsset"
- "ListAssets"
- "GetAsset"
- "UpdateAsset"
- "DeleteAsset"
"2024-01-01"Cabeçalhos
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