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. Se omitido, assume-se o valor «default».

user_id

string Identificador único de usuário, para atualizar um voiceprint* existente. Se fornecido, mas nenhum voiceprint existir no cenário indicado, um erro será retornado. Se omitido, um novo usuário 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

configuration

object Parâmetros de configuração da operação biométrica. Todos os campos são opcionais.

split_mode: string Define a forma na qual o serviço deve cortar os áudios de entrada para obter as frases. Para mais detalhes, consulte a seção Modos de corte. Os valores válidos são AUTO e UTTERANCE. O modo AUTO não pode ser utilizado pela interface REST. O valor padrão é AUTO.
min_speech: integer 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.

max_speech: integer 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.

min_utterances: integer Define o número mínimo de frases 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.

max_utterances: integer Define o número máximo de frases 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.

max_constraint_behavior

string Indica o comportamento quando o valor definido max_speech e/ou max_utterances for ultrapassado. O valor padrão é trim. Os valores válidos são:

trim - Descarta áudio para que o total aproxime-se do limite superior. O áudio pode ser cortado em algum silêncio. O processo continua normalmente (sem erro);
abort - Aborta todo o processo e retorna um erro para o usuário.

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 (_).
gender_detection: bool Habilita (true) ou desabilita (false) a detecção do gênero do locutor. O valor padrão é false. Este parâmetro tem efeito apenas em verificações biométricas.
age_detection: bool Habilita (true) ou desabilita (false) a detecção de idade do locutor. O valor padrão é false. Este parâmetro tem efeito apenas em verificações biométricas.

Os demais boundaries devem conter, cada um deles, um áudio a ser utilizado na operação biométrica. São permitidos o envio de até 10 áudios, cada qual com tamanho de até 5MB. O formato dos áudios depende do valor indicado em media_type, no primeiro boundary. Não é permitido misturar áudios PCM Linear com áudios contendo cabeçalho.

Resposta¶

A resposta é um objeto JSON contendo os seguintes campos:

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

utterances

array Lista de objetos contendo informações sobre as frases identificadas nos áudios fornecidos pelo usuário.

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

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

Exemplo¶

Chamada REST enviando o audio via multipart:

 curl --request POST \
--url http://bmt-dev.cpqd.com.br/bio/bmt/rest/v3/enroll \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--cookie dtCookie=<cookie> \
--form 'enroll={
      "repository_uri": "10.245.15.14:9090",
      "scenario": "nico@sr8khz",

      "configuration": {
              "split_mode": "utterance",
              "min_speech": 1000,
              "max_speech": 120000,
              "min_utterances": 1,
              "max_utterances": 20,
              "max_constraint_behavior": "trim",
              "logging_tag": "CRIS_ENROLL",
              "account_tag":"ACCOUNT_CRIS_ENROLL"
      }
  }
  '\
  --form audio=@<path-to-file>/audio1.wav

Exemplo de resposta:

{
    "transaction_id": "170952487879051776",
    "user_id": "170952489489664000",
    "user_updated": false,
    "voiceprint_updated": false,
    "utterances": [
        {
            "audio_counter": 0,
            "total_duration": 7251,
            "speech_duration": 4360,
            "rejected": false,
            "start_time": 1.46,
            "end_time": 6.37
        }
    ]
}