Mensagens¶

BiometricConfig¶

Parâmetros de configuração comuns da verificação e cadastro. Todos os campos são opcionais.

operation_mode

OperationMode Modo no qual a operação biométrica deve operar. O valor padrão é M_SINGLE.

split_mode

SplitMode - Define a forma na qual o serviço deve cortar os áudios de entrada para obter as frases. O valor padrão é S_AUTO.

speech_detection

bool - Habilita (true) ou desabilita (false) os eventos de detecção automática de início e fim de fala. Quando a funcionalidade está habilitada, a função Verify retornará eventos do tipo StartOfSpeechEvent e EndOfSpeechEvent em qualquer modo de operação. O valor padrão é false.

no_input_timeout

uint32 - Tempo, em milissegundos, no qual o serviço aguardará a entrega da primeira porção de áudio. A contagem começa a partir do momento em que foi feita a chamada de Verify ou Enroll. Se nenhum áudio for transmitido nesse tempo, um erro de timeout será retornado. O valor deve ser de 1000 até 30000. O valor padrão é 10000.

operation_timeout

uint32 - Tempo máximo, em milissegundos, no qual a verificação deve ser concluída. A contagem começa a partir do momento em que foi feita a chamada de Verify ou Enroll. Se a verificação não concluir até esse tempo, um erro de timeout será retornado. O valor deve ser de 1000 até 60000. O valor padrão é 30000.

end_silence

uint32 - Duração mínima do silêncio, em milissegundos, a ser considerado como final de fala em um áudio. O valor deve ser de 500 até 3000. O valor padrão é 1000.

no_speech_timeout

uint32 - Tempo, em milissegundos, que o serviço deve aguardar por um início de fala antes de considerar que não existem mais áudios a serem entregues pelo cliente. A contagem começa a partir do último fim de fala detectado ou da primeira requisição SEND-AUDIO, caso nenhum fim de fala tenha sido detectado até o momento. A contagem para um início de fala é reiniciada (volta a zero e recomeça a contagem) a cada fim de fala. Ao contrário de no_audio_timeout, este timeout continua contabilizando mesmo recebendo áudio, desde que seja silêncio. O valor deve ser de 500 até 10000. O valor padrão é 2000.

no_audio_timeout

uint32 - Tempo, em milissegundos, no qual o serviço aguardará uma nova porção de áudio chegar antes de considerar que não existem mais áudios a serem entregues pelo cliente. A contagem começa a partir do momento em que a última porção de áudio foi recebida pelo serviço e a contagem é reiniciada a cada porção recebida. O valor deve ser de 500 até 10000. O valor padrão é 2000.

min_utterances

uint32 - Define o número mínimo de frases/áudios 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. Esse parâmetro não tem efeito se o modo de verificação for M_CONTINUOUS.

max_utterances

uint32 - Define o número máximo de frases/áudios 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. Esse parâmetro não tem efeito se o modo de verificação for M_CONTINUOUS.

min_speech

uint32 - 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. Esse parâmetro não tem efeito se o modo de verificação for M_CONTINUOUS.

max_speech

uint32 - 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. Esse parâmetro não tem efeito se o modo de verificação for M_CONTINUOUS.

window_size

uint32 - Tamanho da janela a ser considerada na verificação M_CONTINUOUS. O tamanho da janela indica quantas das últimas sentenças serão consideradas na verificação. Os valores válidos são de 1 até 10. O valor padrão é 1.

max_constraint_behavior

string - Indica o comportamento quando os valores definidos por max_utterances e/ou max_speech forem ultrapassados. O valor padrão é trim. Os valores válidos são:

trim: Descarta o áudio excedente para que o total aproxime-se do limite superior. Se o limiar atingido for max_speech, o áudio pode ser cortado em algum silêncio; se o limiar atingido for max_utterances, áudios excedentes serão descartados. 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 (_).

EnrollmentParams¶

Parâmetros de uma chamada de cadastro biométrico.

repository_uri

string URL do repositório biométrico.

scenario

string Identificador único do cenário, incluindo o modelo. Deve seguir os critérios definidos em Cenário.

user_id

uint64 Identificador único de usuário. Deve ser informado para atualizar um voiceprint existente. Se fornecido, mas nenhum voiceprint existir no cenário indicado, um erro será retornado. Se omitido, um novo voiceprint será criado.

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_enrollment_score

float Limiar de aceitação ao comparar os áudios fornecidos no cadastro. O valor deve ser de -1.0 até 1.0. Se o score calculado durante o cadastro for maior ou igual a este limiar, o voiceprint do usuário será criado ou atualizado. Caso contrário a operação de cadastro resultará em erro. Para mais informações, consulte o campo score em EnrollmentResultEvent.

configuration

BiometricConfig Parâmetros de configuração do cadastro.

VerificationParams¶

Parâmetros de uma chamada de verificação biométrica.

repository_uri

string URL do repositório biométrico.

scenario

string identificador único do cenário, incluindo o modelo. Deve seguir os critérios definidos em Cenário Campo obrigatório.

user_ids

repeated uint64 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. O valor deve ser de -1.0 até 1.0. 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.

configuration

BiometricConfig Parâmetros de configuração da verificação.

UtteranceInfo¶

Informações sobre as frases identificadas nos áudios fornecidos pelo usuário.

audio_counter: uint32 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: uint32 Duração total da frase, em milissegundos.
speech_duration: uint32 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.

ResultInfo¶

Resultado de verificação biométrica de um usuário específico.

user_id: uint64 Identificador único do usuário ao qual o resultado se refere.
score: float Score obtido considerando todos os áudios já processados até o momento. No caso do modo de operação M_CONTINUOUS, somente um número específico de áudios é considerado (mais detalhes em VerificationParams). Em caso de erro, deve ser preenchido com zero.
decision: Decision Decisão da verificação ou cadastro biométrico. Em caso de erro, deve ser preenchido com D_UNDECIDED.
detail: ResultDetail Detalhes sobre os resultados parciais que compõem a decisão final.
audio_length: uint32 - Quantidade de áudio, em milissegundos, utilizado para gerar o resultado.
error: ErrorInfo Informações sobre um erro na operação com o usuário indicado.

VerificationResultEvent¶

Resultado de uma verificação biométrica.

transaction_id: uint64 Identificador único da transação.
results: repeated ResultInfo Lista de objetos contendo os resultados das verificações biométricas.
utterances: repeated UtteranceInfo Lista de objetos contendo as informações sobre cada frase processada.

EnrollmentResultEvent¶

Resultado de um cadastro biométrico.

transaction_id: uint64 Identificador único da transação.
user_id: uint64 Identificador único do usuário criado pelo serviço. Se a operação foi de atualização, este identificador será igual ao informado no campo homônimo da requisição.
user_updated: bool Indica se a operação alterou um usuário existente (true) ou se foi criado um novo usuário na base (false).
voiceprint_updated: bool Indica se a operação atualizou um voiceprint existente de um usuário (true) ou se foi criado um novo voiceprint (false). Esse campo poderá ser true somente se a operação atualizou um usuário (i.e. o campo user_updated possui o valor true).
score: float Score de cadastro, resultante da comparação entre os áudios fornecidos no cadastro. No caso de uma atualização, também considera o voiceprint anterior. Este valor pode ser utilizado para detectar casos onde áudios de diferentes locutores são fornecidos. Para mais informações, consulte o campo min_enrollment_score em EnrollmentParams.
utterances: repeated UtteranceInfo Lista de objetos contendo as informações sobre cada frase processada.

StartOfSpeechEvent¶

Notifica que o início de fala foi detectado no áudio.

audio_counter: uint32 Contador do áudio, definido pelo cliente no momento da transmissão.
time: uint64 Posição no áudio, em milissegundos, onde o início de fala foi detectado.

EndOfSpeechEvent¶

Notifica que o fim de fala foi detectado no áudio.

audio_counter: uint32 Contador do áudio, definido pelo cliente no momento da transmissão.
time: uint64 Posição no áudio, em milissegundos, onde o fim de fala foi detectado.

VerificationEvent¶

Evento de uma verificação biométrica. Apenas um dos campos abaixo será preenchido:

start_of_speech: StartOfSpeechEvent Evento da detecção de início de fala.
end_of_speech: EndOfSpeechEvent Evento da detecção de fim de fala.
result: VerificationResultEvent Evento contendo o resultado da verificação biométrica.

EnrollmentEvent¶

Evento de um cadastro biométrico. Apenas um dos campos abaixo será preenchido (one_of):

start_of_speech: StartOfSpeechEvent Evento da detecção de início de fala.
end_of_speech: EndOfSpeechEvent Evento da detecção de fim de fala.
result: EnrollmentResultEvent Evento contendo o resultado do cadastro biométrico.

AudioPayload¶

Objeto contendo informações e o conteúdo binário de áudios.

audio_counter: uint32 Contador de áudios, definido pelo cliente no momento da transmissão. Se o áudio estiver fragmentado, cada fragmento deve possuir o mesmo valor para esse campo. Quando há mudança nesse contador, o serviço assume que o cliente está passando um novo áudio. O contador deve iniciar em zero e incrementar em 1 a cada áudio transmitido. O valor máximo é 256.
data: bytes Conteúdo binário do áudio, podendo ser um fragmento do áudio original. O formato do áudio é definido na chamada de Verify e Enroll. Recomenda-se que o áudio seja transmitido em fragmentos de 8KiB até 1024KiB. A quantidade máxima de dados nesse campo é de 2048KiB.
completed: bool Indica se todos áudios foram transmitidos (true) ou não (false). O valor padrão é false. O último objeto AudioPayload transmitido pelo cliente deveria definir esse campo como true. Se o cliente não puder determinar quando o áudio acabou, recomenda-se ativar a detecção de fala (speech_detection em BiometricConfig) para que o serviço decida automaticamente.

Decision¶

Enumeração com as decisões de verificação biométrica.

D_ACCEPTED: O score obtido na verificação é maior ou igual ao limiar e não foi detectada fraude.
D_REJECTED: O score obtido na verificação é menor que o limiar ou foi detectada fraude.
D_UNDECIDED: Não foi definido um limiar de aceitação e não foi detectada fraude.

ErrorInfo¶

Reúne informações sobre um erro relacionado a um usuário.

code: uint32 Código de erro.
message: string Mensagem de erro.

ResultDetail¶

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

biometric_decision: enum Decision Decisão considerando apenas o resultado da verificação ou cadastro biométrico. Em caso de erro, deve ser preenchido com D_UNDECIDED.
antispoofing_decision: enum Decision Decisão considerando apenas o anti-spoofing. Em caso de erro, deve ser preenchido com D_UNDECIDED.