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 verify, 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. Deve seguir os critérios definidos em Cená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

verification_threshold

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, NONE e UTTERANCE para a interface REST. Se AUTO for informado o serviço decide qual modo de corte será utilizado. 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 for ultrapassado, 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 for ultrapassado, 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, será preenchido com zero (valor padrão para o campo).

decision
string Decisão da verificação ou cadastro biométrico. Em caso de erro, 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, será preenchido com UNDECIDED.

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

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 o áudio de entrada correspondente. 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": "ura800",

   "verification_threshold": 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
        }
    ]
}