Mensagens¶

Esta seção apresenta as mensagens adicionais que são utilizadas em conjunto daquelas definidas nas APIs. Os campos são obrigatórios por padrão, exceto no casos onde é indicado um valor padrão.

A interface GRPC do serviço é definida utilizando proto3 , logo é importante observar que:

Todos os campos são considerados opcionais do ponto de vista do GRPC e campos omitidos terão o valor padrão, conforme descrito na seção Default field values da especificação do proto3. A obrigatoriedade de campos deste documento, indicada no texto desta especificação, é garantida pelo serviço em si.
Os tipos de dados utilizados nos campos, e que não estejam especificados neste documento, são parte do proto3 e suas definições podem ser consultadas na seção Scalar Value Types.

BiometricConfig¶

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

capture_mode

CaptureMode Modo no qual o áudio de entrada será capturado e entregue à aplicação. O valor padrão é BATCH.

operation_mode

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

no_input_timeout

uint32 - Tempo, em milissegundos, no qual o serviço aguardará algum áudio chegar antes de encerrar a operação biométrica por inatividade. Se o tempo for ultrapassado, a solução encerrará a operação biométrica com um erro. A contagem sempre inicia no momento em que a chamada gRPC da operação biométrica é iniciada.

No modo de captura BATCH, a aplicação precisa enviar o primeiro AudioPayload antes deste tempo ser ultrapassado, ainda que o áudio enviado não contenha fala.

No modo de captura STREAMING, a aplicação precisa enviar algum AudioPayload contendo fala antes deste tempo ser ultrapassado. Neste caso, a contagem de tempo continuará se a aplicação somente enviar áudio sem fala. A presença de fala é indicada para a aplicação através do evento StartOfSpeechEvent.

O valor padrão é 5000 e poderá ser definido entre 500 até 30000. Deve ser maior ou igual ao valor especificado em end_silence.

no_speech_timeout

uint32 - Tempo, em milissegundos, que o serviço deve aguardar pela chegada de algum áudio antes de considerar que não existem mais conteúdo a ser entregue pela aplicação. Se o tempo for ultrapassado, a solução tenta completar a operação biométrica com o conteúdo recebido até o momento. Este timeout sempre inicia depois que algum conteúdo válido já foi recebido.

No modo de captura BATCH, a contagem inicia ao receber o primeiro AudioPayload e é reiniciada a cada AudioPayload subsequente.

No modo de captura STREAMING, a contagem inicia na primeira detecção de final de fala e é reiniciada a cada final de fala subsequente. Finais de fala são indicados para a aplicação através pelo evento EndOfSpeechEvent.

O valor padrão é 5000 e poderá ser definido entre 500 até 30000. Deve ser maior ou igual ao valor especificado em end_silence.

min_utterances

uint32 - Define o número mínimo de enunciados que devem ser transmitidos 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 enunciados seja atingido.

O valor padrão é 1 e poderá ser definido entre 1 até 20. 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 CONTINUOUS.

max_utterances

uint32 - Define o número máximo de enunciados que o serviço aceitará. Ao atingir esse limite, o serviço responderá uma decisão diferente de undecided.

O valor será de 1 até 20, e será maior ou igual ao valor de min_utterances. O valor padrão é o mesmo valor de min_utterances. Se a quantidade de enunciados ultrapassar este valor, o comportamento resultante é definido por max_constraint_behavior.

Esse parâmetro não tem efeito se o modo de verificação for CONTINUOUS.

min_speech

uint32 - Duração mínima, em milissegundos, de fala. O valor 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 CONTINUOUS.

max_speech

uint32 - Duração máxima, em milissegundos, de fala. O valor será de 1000 até 120000, e não deve ser inferior ao valor de min_speech. 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 CONTINUOUS.

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 e o processo continua normalmente (sem erro);
abort: Aborta todo o processo e retorna um erro para a aplicação.

end_silence

uint32 - Duração de um silêncio, em milissegundos, para que seja considerado como final de fala. O silêncio de final de fala define o ponto onde o áudio poderá ser cortado para gerar um enunciado. O valor padrão é 250 e pode ser definido entre 10 a 2000.

logging_tag

string - Tag a ser inserida nos logs do serviço para rastreio de requisições. O valor 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 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. Campo obrigatório. 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 fornecido. O valor padrão é auto. Saiba mais sobre os formatos aceitos em Formatos de áudio
enrollment_threshold: float - Limiar de aceitação ao comparar os áudios fornecidos no cadastro. 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. Campo obrigatório.
scenario: string - identificador único do cenário, incluindo o modelo. Campo obrigatório. Deve seguir os critérios definidos em Cenário.
user_ids: uint64 - Lista de identificadores de usuário que devem ser verificados com os áudios fornecidos pela aplicação. Podem ser indicados de 1 a 128 identificadores. Serão retornados resultados individuais para cada um destes usuários. Campo obrigatório.
media_type: string - Formato do áudio fornecido. O valor padrão é auto. Saiba mais sobre os formatos aceitos em Formatos de áudio
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.
configuration: BiometricConfig - Parâmetros de configuração da verificação.

UtteranceInfo¶

Informações sobre os enunciados identificados nos áudios fornecidos pela aplicação.

audio_counter: uint32 - Contador de áudios, indicando a qual áudio de entrada que o enunciado corresponde. O primeiro áudio de entrada é representado pelo valor 0 (zero) e o valor é incrementado a cada áudio.
utterance_duration: uint32 - Duração total do enunciado, em milissegundos.
utterance_counter: uint32 - Identificador do enunciado. O primeiro enunciado é representado pelo valor 0 (zero) e o valor é incrementado a cada enunciado originado do mesmo áudio. A contagem reinicia para cada áudio de entrada.
ignored: boolean - Indica se o enunciado foi ignorado (true) ou não (false) durante o processamento da operação.
ignore_cause: string - Caso o valor do campo is_ignored seja true, este campo indica o motivo pelo qual o enunciado foi ignorado.
start_time: uint32 - Marcação temporal do início da fala, em milissegundos, relativo ao áudio de entrada.
end_time: uint32 - Marcação temporal do fim da fala, em milissegundos, 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 considerando o modo de operação selecionado. Em caso de erro, será preenchido com 0 (zero), valor padrão para o campo.
decision: Decision - Decisão da verificação biométrica. Em caso de erro, será preenchido com UNDECIDED.
detail: ResultDetail - Detalhes sobre os resultados parciais que compõem a decisão final.
error: ErrorInfo - Informações sobre um erro na operação com o usuário indicado. Seu valor padrão é vazio em caso de sucesso.

VerificationResultEvent¶

Resultado de uma verificação biométrica.

transaction_id: uint64 - Identificador único da transação.
results: ResultInfo - Lista de objetos contendo os resultados das verificações biométricas.
utterances: UtteranceInfo - Lista de objetos contendo as informações sobre cada frase processada. Este campo não é preenchido caso o modo de operação seja CONTINUOUS.

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_status ModificationStatus

string - Indica o estado de modificação do usuário.

voiceprint_status ModificationStatus

string - Indica o estado de modificação do voiceprint.

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 enrollment_threshold em EnrollmentParams.

utterances

UtteranceInfo Lista de objetos contendo as informações sobre cada enunciado processado.

decision

string Refere-se a decisão do cadastro biométrico resultante da validação do enrollment_threshold fornecido e o score da verificação ocorrida entre os áudios fornecidos no cadastro; no caso de uma atualização, ocorrida na comparação com o voiceprint anterior. Se o limiar não foi informado ou ocorreu algum 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 ou ocorreu erro.

detail

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

StartOfSpeechEvent¶

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

audio_counter: uint32 - Contador do áudios, indicando o áudio de entrada correspondente. O primeiro áudio é representado pelo valor 0 (zero) e incrementado a cada áudio.
utterance_counter: uint32 - Identificador do enunciado a qual o evento se refere. Informações sobre o enunciado estarão presentes no campo utterances em VerificationResultEvent
timestamp: 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 de áudios. O primeiro áudio de entrada é representado pelo valor 0 (zero) e o valor é incrementado a cada áudio.
utterance_counter: uint32 - Identificador do enunciado a qual o evento se refere. Informações sobre o enunciado estarão presentes no campo utterances em VerificationResultEvent.
timestamp: 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, utilizado somente no modo de captura streaming.
end_of_speech: EndOfSpeechEvent - Evento da detecção de fim de fala, utilizado somente no modo de captura streaming.
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. Um payload pode representar um áudio completo ou parcial.

data: bytes - Conteúdo binário do áudio, podendo ser um fragmento do áudio original se o modo streaming estiver habilitado; caso contrário, o conteúdo de cada AudioPayload é considerado como um arquivo de áudio independente.

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: boolean - Indica se o conteúdo atual é a última porção de áudio que a aplicação enviará (true) ou se há mais áudio para ser transmitido (false). O valor padrão é false.

Idealmente, o último AudioPayload transmitido pela aplicação deve definir esse campo como true. Se a aplicação não puder determinar quando o áudio acabou, o campo no_speech_timeout de BiometricConfig pode ser ajustado para controlar o timeout baseado na ausência de fala.

ErrorInfo¶

Reúne informações sobre um erro relacionado a uma operação biométrica.

code: uint32 - Código de erro. Se a operação foi executada com sucesso, o valor zero será retornado.
message: string - Mensagem de erro. Se a operação foi executada com sucesso, nenhuma mensagem será retornada.

ResultDetail¶

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

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