POST rest/v3/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.

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

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

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.

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

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

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

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 1

Chamada REST enviando o audio via multipart:

 curl --request POST \
--url http://speechd.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": "exemplo1@sr8khz",

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

Exemplo 2

Chamada REST enviando o audio via multipart:

 curl --request POST \
--url http://speechd.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": "exemplo2@sr8khz",
      "min_enrollment_score": -1,

      "configuration": {
            "split_mode": "auto",
             "min_speech":"1000",
             "max_speech":"120000"
             "max_utterances": "20",
             "max_constraint_behavior": "abort",
             "logging_tag": "exemplo_ENROLL_REST",
             "account_tag": "exemplo_ACCOUNT_Enroll"
      }
  }
  ' \
  --form 'audio=@C:\IC\BIOMETRIA\AUDIOS\diversos\Alfredo_08_d6101_s3510.wav' \
  --form 'audio=@C:\IC\BIOMETRIA\AUDIOS\diversos\Alfredo_09_d4712_s4250.wav'

Exemplo de resposta - 1:

{
    "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
        }
    ]
}

Exemplo de resposta - 2 :

{
	"transaction_id": "204211614264595968",
	"user_id": "204211620405053440",
	"user_updated": false,
	"voiceprint_updated": false,
	"score": 0.57035404,
	"utterances": [
		{
			"audio_counter": 0,
			"total_duration": 6101,
			"speech_duration": 3510,
			"rejected": false,
			"start_time": 0.0,
			"end_time": 6.101375
		},
		{
			"audio_counter": 1,
			"total_duration": 4713,
			"speech_duration": 4250,
			"rejected": false,
			"start_time": 0.0,
			"end_time": 4.7129374
		}
	]
}