enroll¶

Efetua um cadastro biométrico com um ou mais áudios do mesmo locutor.

Requisição¶

A requisição deve estar estruturada como multipart (Content-Type definido como multipart/form-data). O primeiro boundary, denominado enroll, 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_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. Se nenhum limiar for especificado, o cadastro sempre será efetuado

Para mais informações, consulte o campo score da resposta da requisição.

configuration

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

Os demais boundaries devem conter, cada um deles, um áudio a ser utilizado na operação biométrica. A requisição pode conter até 10 áudios, cada qual com tamanho de até 5MiB. Se o limite for excedido, o endpoint deve retornar HTTP 400 com um objeto ErrorInfo descrevendo problema.

Em caso de erro na validação dos argumentos de entrada ou no cadastro biométrico, o endpoint deve retornar HTTP 400 com um objeto ErrorInfo descrevendo problema.

Não é permitido misturar áudios PCM Linear com áudios contendo cabeçalho.

Resposta¶

Refere-se ao resultado de um cadastro biométrico. A resposta é um objeto JSON contendo os seguintes campos:

transaction_id

uint64 - Identificador único da transação. Contém um valor decimal positivo de 63-bits.

user_id

uint64 - Identificador único do usuário criado pelo serviço. Contém um valor decimal positivo de 63-bits. Se a operação foi de atualização, este identificador será igual ao informado no campo homônimo da requisição.

user_status

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

voiceprint_status

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

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 da requisição de cadastro.

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

Exemplo 1¶

Chamada REST enviando o audio via multipart:

curl --request POST \
--url http://10.245.15.2/bmt/rest/v3/enroll \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--header 'User-Agent: insomnia/8.6.0' \
--form 'enroll={
  "repository_uri": "http://service-repository-teste:9090",
  "scenario": "demo",
  "media_type": "auto",
  "enrollment_threshold": 0.0,
  "configuration": {
          "max_constraint_behavior": "trim",
          "min_speech": 1000,
          "max_speech": 120000,
          "min_utterances": 1,
          "max_utterances": 20,
          "end_silence": 200,
          "logging_tag": "exemplo_ENROLL",
          "account_tag": "ACCOUNT_exemplo_ENROLL"
      }
}' \
--form audio=@<path-to-file>/claudia_enroll.wav

Exemplo de resposta - 1:

{
    "transaction_id": "490490449149034496",
    "user_id": "490490457298569216",
    "user_status": false,
    "voiceprint_status": false,
    "score": 0.53105104,
    "utterances": [
        {
            "audio_counter": 0,
            "utterance_counter": 0,
            "utterance_duration": 4520,
            "ignored": false,
            "start_time": 550,
            "end_time": 5410
        },
        {
            "audio_counter": 0,
            "utterance_counter": 1,
            "utterance_duration": 2390,
            "ignored": false,
            "start_time": 6980,
            "end_time": 9400
        },
        {
            "audio_counter": 0,
            "utterance_counter": 2,
            "utterance_duration": 2380,
            "ignored": false,
            "start_time": 9880,
            "end_time": 12440
        },
        {
            "audio_counter": 0,
            "utterance_counter": 3,
            "utterance_duration": 5170,
            "ignored": false,
            "start_time": 16120,
            "end_time": 21860
        },
        {
            "audio_counter": 0,
            "utterance_counter": 4,
            "utterance_duration": 3440,
            "ignored": false,
            "start_time": 23570,
            "end_time": 27010
        },
        {
            "audio_counter": 0,
            "utterance_counter": 5,
            "utterance_duration": 4080,
            "ignored": false,
            "start_time": 27590,
            "end_time": 34180
        },
        {
            "audio_counter": 0,
            "utterance_counter": 6,
            "utterance_duration": 2790,
            "ignored": false,
            "start_time": 34900,
            "end_time": 38020
        }
    ],
    "decision": "ACCEPTED"
}