verify¶

Efetua uma verificação biométrica com um ou mais áudios do mesmo locutor. É possível efetuar a verificação de vários usuários diferentes utilizando os áudios fornecidos.

Requisição¶

A requisição deve estar estruturada como multipart (Content-Type definido como multipart/form-data). O primeiro boundary, denominado enroll, deve conter um objeto JSON (application/json) com os seguintes campos:

repository_uri

string URL do repositório biométrico.

scenario

string Identificador único do cenário, incluindo o modelo. Campo obrigatório.

user_ids

string array Lista de identificadores de usuário que devem ser verificados com os áudios fornecidos pelo cliente. Serão retornados resultados individuais para cada um destes usuários.

media_type

string Formato do áudio que será fornecido. Os valores válidos para este campo são:

auto: O formato é detectado automaticamente através do cabeçalho presente no conteúdo binário. Os formatos suportados são: FLAC, Waveform (cabeçalho RIFF), MPEG-Layer 3 (MP3) e Ogg Vorbis.
pcm/8000/16/mono: PCM Linear 8kHz 16bps Mono
pcm/16000/16/mono: PCM Linear 16kHz 16bps Mono

min_verification_score

float Limiar de aceitação. Se o score da verificação for maior ou igual a este limiar, a decisão será ACCEPTED, caso contrário será REJECTED. Caso não seja informado, a decisão permanece UNDECIDED. Para mais detalhes, consulte o campo decision na resposta.

configuration

object Parâmetros de configuração da operação biométrica. Todos os campos são opcionais.

split_mode: string Define a forma na qual o serviço deve cortar os áudios de entrada para obter as frases. Para mais detalhes, consulte a seção Modos de corte. Os valores válidos são AUTO e UTTERANCE. O modo AUTO não pode ser utilizado pela interface REST. O valor padrão é AUTO.
min_speech: integer Duração mínima, em milissegundos, de fala. O valor deve ser de 1000 até 120000. O valor padrão é 1000. Se esse limiar não for atingido, a operação encerra com erro.

max_speech: integer Duração máxima, em milissegundos, de fala. O valor deve ser de 1000 até 120000. O valor padrão é 120000. Se esse limiar não for atingido, o comportamento resultante é definido por max_contraint_behavior.

min_utterances: integer Define o número mínimo de frases que devem ser transmitidas para que o serviço comece a gerar uma decisão. O serviço não irá gerar uma decisão até que o número mínimo de frases seja atingido. O valor deve ser de 1 até 20. O valor padrão é 1. Se esse limiar não for atingido, a operação encerra com erro.

max_utterances: integer Define o número máximo de frases que o serviço aceitará. Ao atingir esse limite, o serviço responderá a decisão com algum valor que não seja «undecided». O valor deve ser de 1 até 20, e deve ser maior ou igual ao valor de min_utterances. O valor padrão é o mesmo valor de min_utterances. Se esse limiar não for atingido, o comportamento resultante é definido por max_contraint_behavior.

max_constraint_behavior

string Indica o comportamento quando o valor definido max_speech e/ou max_utterances for ultrapassado. O valor padrão é trim. Os valores válidos são:

trim - Descarta áudio para que o total aproxime-se do limite superior. O áudio pode ser cortado em algum silêncio. O processo continua normalmente (sem erro);
abort - Aborta todo o processo e retorna um erro para o usuário.

logging_tag

string Tag a ser inserida nos logs do serviço para rastreio de requisições. O valor deve ser uma string contendo até 32 caracteres e os caracteres válidos são: letras (não acentuadas), números, traços (-) e sublinhas (_).

account_tag

string Tag a ser inserida no registro de tarifação, permitindo segregar o consumo em categorias. O valor deve ser uma string contendo até 32 caracteres e os caracteres válidos são: letras (não acentuadas), números, traços (-) e sublinhas (_).

Os demais boundaries devem conter, cada um deles, um áudio a ser utilizado na operação biométrica. São permitidos o envio de até 10 áudios, cada qual com tamanho de até 5MiB. O formato dos áudios depende do valor indicado em media_type, no primeiro boundary. Não é permitido misturar áudios PCM Linear com áudios contendo cabeçalho.

Resposta¶

A resposta é um objeto JSON contendo os seguintes campos:

transaction_id

string Identificador único da transação. Contém um valor decimal positivo de 63-bits.

results

array Lista de objetos contendo os resultados das verificações biométricas. Cada objeto possui os seguintes campos:

user_id: string Identificador único do usuário ao qual o resultado se refere.
score: float Score obtido considerando todos os áudios. Em caso de erro, deve ser preenchido com zero.

decision
string Decisão da verificação ou cadastro biométrico. Em caso de erro, deve ser preenchido com UNDECIDED.

ACCEPTED - O score obtido na verificação é maior ou igual ao limiar e não foi detectada fraude.

REJECTED - O score obtido na verificação é menor que o limiar ou foi detectada fraude.

UNDECIDED - Não foi definido um limiar de aceitação e não foi detectada fraude.

detail

string Detalhes sobre os resultados parciais que compõem a decisão final.

biometric_decision - Decisão considerando apenas o resultado da verificação ou cadastro biométrico. Em caso de erro, deve ser preenchido com UNDECIDED.

antispoofing_decision - Decisão considerando apenas o anti-spoofing. Em caso de erro, deve ser preenchido com UNDECIDED.

gender string Gênero do locutor, detectado através dos áudios processados.

FEMALE - Feminino.

MALE - Masculino.

UNKNOWN - Gênero não identificado ou classificação desabilitada.

age
string Idade do locutor, detectada através dos áudios processados.

CHILD - Pessoas com até 12 anos de idade.

TEENAGER - Pessoas de 13 até 19 anos de idade.

YOUNG_ADULT - Pessoas de 20 até 39 anos de idade.

ADULT - Pessoas de 40 até 59 anos de idade.

SENIOR - Pessoas a partir de 60 anos de idade.

UNKNOWN - Idade desconhecido ou classificação desabilitada.

audio_length
integer Quantidade de áudio, em milissegundos, utilizado para gerar o resultado.

error
object Informações sobre um erro na operação com o usuário indicado.

code
integer Código de erro. Se a operação foi executada com sucesso, este campo conterá o valor zero.

message
string Mensagem de erro. Se a operação foi executada com sucesso, este campo estará vazio.

utterances

array Lista de objetos contendo informações sobre as frases identificadas nos áudios fornecidos pelo usuário.

audio_counter
integer Contador de áudios, indicando a qual áudio de entrada que a frase corresponde. O primeiro áudio de entrada é representado pelo valor 0 (zero). Quando é utilizado o modo de corte S_UTTERANCE ou S_FIXED, podem existir várias frases com o mesmo valor para esse campo.

total_duration
integer Duração total da frase, em milissegundos.

speech_duration
integer Quantidade de fala na frase, em milissegundos.

rejected
bool Indica se a frase foi rejeitada (true) ou não (false) durante o processamento da operação.

rejected_cause
string Caso o valor do campo rejected seja true, este campo indica o motivo pelo qual a frase foi rejeitada.

start_time
float Marcação temporal do início da fala, em segundos, relativo ao áudio de entrada.

end_time
float Marcação temporal do fim da fala, em segundos, relativo ao áudio de entrada.

Exemplo¶

Chamada REST enviando o audio via multipart:

curl --request POST \
--url https://speechd.cpqd.com.br/bio/rest/v3/verify \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--cookie dtCookie= <cookie> \
--form 'verify={
   "repository_uri": "speechd.cpqd.com.br:9092",
   "user_ids": ["166974241697171456"],
   "scenario": "exemplo@sr8khz",

   "min_verification_score": 0.5,
   "configuration": {
        "split_mode": "AUTO",
        "min_speech": 1000,
        "max_speech": 120000,
        "min_utterances": 1,
        "max_utterances": 20,
        "max_constraint_behavior": "trim",
        "logging_tag": "EXEMPLO_VERIFY"
    }
    }
--form audio=@<path-to-file>/audio1.wav

Resultado JSON:

{
    "transaction_id": "166974655326849536",
    "results": [
        {
            "user_id": "166974241697171456",
            "score": 0.4303926,
            "audio_length": 12432,
            "decision": "REJECTED",
            "detail": {
                "biometric_decision": "REJECTED",
                "antispoofing_decision": "ACCEPTED"
            }
        }
    ],
    "utterances": [
        {
            "audio_counter": 0,
            "total_duration": 12432,
            "speech_duration": 7160,
            "rejected": false,
            "start_time": 0.0,
            "end_time": 12.43225
        }
    ]
}