Mensagens¶

BiometricConfig¶

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

min_utterances

uint32 - Define o número mínimo de enunciados que devem ser transmitidos para efetuar a operação biométrica.

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.

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.

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.

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.

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 (_).

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.

VerificationRequest¶

Parâmetros exclusivos da requisição 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.
user_ids: repeated string - Lista de identificadores de usuário que devem ser verificados com os áudios fornecidos pela aplicação. Os identificadores devem ser informados como um valores decimais positivos de até 63-bits. Podem ser indicados de 1 até 128 identificadores. Serão retornados resultados individuais para cada um destes usuários.
media_type: string - Formato do áudio, conforme especificado em Formatos de áudio. O valor padrão é auto.
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.

VerificationResponse¶

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

transaction_id: string - Identificador único da transação. Contém um valor decimal positivo de 63-bits.
results: repeated ResultInfo - Lista de objetos contendo os resultados das verificações biométricas. Haverá uma entrada para cada usuário indicado na requisição.
utterances: repeated UtteranceInfo - Lista de objetos contendo informações sobre os enunciados identificados nos áudios fornecidos pelo usuário. Este campo pode estar vazio ou ser omitido caso nenhum áudio tenha sido processado.

EnrollmentRequest¶

Parâmetros de uma requisição 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

string - Identificador único de usuário, caso a operação deva atualizar um voiceprint existente. O identificador deve ser informado como um valor decimal positivo de até 63-bits. 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 em Formatos de áudio. O valor padrão é auto.

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. Se nenhum limiar for especificado, o cadastro sempre será efetuado.

Para mais informações, consulte o campo score de EnrollmentResponse.

EnrollmentResponse¶

Resultado de um cadastro biométrico.

transaction_id

string - Identificador único da transação.

user_id

string - Identificador único do usuário. Se a operação foi de atualização, este identificador será igual ao informado no campo user_id de EnrollmentRequest.

user_status

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

voiceprint_status

ModificationStatus - 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 EnrollmentRequest.

utterances

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

decision

Decision - Decisão do cadastro biométrico. Se o limiar não foi informado ou ocorreu algum erro, esta campo será preenchido com UNDECIDED.

detail

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

ResultInfo¶

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

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 0 (zero), valor padrão para o campo.
decision: Decision - Decisão da verificação ou cadastro biométrico. 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.

ConstraitBehavior¶

Enumeração com os comportamentos da solução quando a quantidade de áudio recebido exceder os limites. O áudio excedente consiste nos enunciados que vierem depois que max_utterances e/ou max_speech forem ultrapassados.

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.

Decision¶

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

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.

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: AntispoofingDecision - Decisão considerando apenas o anti-spoofing. Em caso de erro, será preenchido com UNDECIDED.

AntispoofingDecision¶

Detalhamento da decisão do anti-spoofing.

antispoofing_decision

Apresenta o resultado da análise de anti-spoofing:

UNDECIDED - ocorre caso ocorra erro na execução do anti-spoofing;
ACCEPTED - indica que após análise do audio o mesmo foi rejeitado;
REJECTED - indica que após análise do audio o mesmo foi rejeitado;

antispoofing_reason

Indica o motivo da rejeição. Caso a decisão seja ACCEPTED ambos parâmetros retornarão o valor false.

synthetic_rejection - boolean - Se true indica que o audio avaliado é sintético;
history_rejection - boolean - Se true indica que o audio avaliado é um replay;

Embora ambos motivos possam ocorrer, o motivo de rejeição considerado será o da primeira análise finalizada como true.: Caso o primeiro audio do cadastro seja rejeitado pelo anti-spoofing o resultado do cadastro biométrico será de erro e o motivo será retornado juntamente com a mensagem de erro.

ModificationStatus¶

Enumeração com os estados de modificação de uma entidade.

UNCHANGED: Nenhuma modificação foi realizada.
CREATED: Uma entidade foi criada.
UPDATED: Uma entidade foi atualizada/modificada.