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 num início de fala e é 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, caso a operação deva 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, conforme especificado na seção Formatos de áudio.

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 dentificador ú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, conforme especificado na seção Formatos de áudio.

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 início 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 início 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 BiometricParams) 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.