POST rest/v2/verify

Realiza a verificação biométrica com o upload de um arquivo de áudio.

Requisição

A requisição deve estar formatada como multipart/form-data. O primeiro campo, denominado verify deve ser um objeto JSON e conter os seguintes campos:

Campo

Tipo

Descrição

repository_uri

string

URL do repositório biométrico

id

string

Lista separada por vírgulas com os identificadores de voiceprint. O envio de mais de um voiceprint realiza a identificação biométrica (1:N)

min_verification_score

double

Valor do limiar de aceitação Valor válido entre -1.0 e 1.0 (opcional).

min_speech

integer

Duração mínima do tempo de fala no áudio para verificação (em ms). Valor padrão = 1000 (opcional, mínimo), Valores válidos de 1000 a 120000.

max_speech

integer

Duração máxima do tempo de fala no áudio para verificação (em ms). Valor padrão = 1000 (opcional), Valores válidos de 1000 a 120000. A duração máxima do tempo de fala permitida na verificação é de 120000 (ms).

min_utterances

integer

Quantidade mínima de áudios a serem processados. Valor padrão = 1.

max_utterances

integer

Quantidade máxima de áudios a serem processados. Valor padrão = 10.

max_constraint_behavior

string

Indica o comportamento quando os valores definidos por max_utterances e/ou max_speech forem ultrapassados. Valor padrão = trim (opcional). Os valores válidos são: trim - Descarta áudio para que o total aproxime-se do limite superior. Se o limiar atingido for max_speech, o áudio pode ser cortado em algum silêncio; se o limiar atingido for max_utterances, áudios excedentes serão descartados. O processo continua normalmente (sem erro); abort - Aborta todo o processo e retorna um erro para o usuário.

logging_tag

string

Campo livre inserido no log e histórico para permitir o rastreio da requisição (opcional)

channel

string

Indica o tipo de canal do qual o áudio originou. (opcional)

A seguir devem ser especificados um ou mais campos, nomeados pelo prefixo audio. Esses campos devem conter os áudios a serem utilizados em cada verificação.

Atualmente suportamos os seguintes formatos de áudio (media-type):

  • audio/wav

  • audio/mp3

  • audio/ogg

  • audio/flac

  • audio/raw - formato PCM Linear com a taxa de 16kHz (conforme o modelo instalado)

  • application/octet-stream - o stream deve possuir cabeçalho e ter um formato suportado

Resposta

A resposta é um objeto com os seguintes campos:

  • transaction_id [string] - Identificador da transação, útil para rastreio em log e histórico

  • voiceprint [array] - Lista de objetos contendo o resultado para cada voiceprint. Ordenado em ordem decrescente com base no score, cada objeto tem o formato abaixo:

    • id [string] - Identificador do voiceprint.

    • verification [object] - Objeto contendo o resultado da verificação, caso o voiceprint tenha sido recuperado.

      • score [double] - score da verificação biometria.

      • decision [string] - Decisão baseado no limiar de aceitação e outros critérios. Os valores válidos são: ACCEPTED, REJECTED, UNDECIDED.

    • error [object] - Indica a ocorrência de um erro na verificação desse voiceprint (opcional).

      • code [string] - código do erro

      • message [string] - mensagem com detalhamento do erro

  • audio_info [array] - Vetor de objetos com informações sobre os áudios utilizados.

    • audio_duration [integer] - duração do áudio (ms)

    • speech_duration [integer] - duração da fala (ms)

    • channel [string] - Indica o tipo de canal do qual o áudio originou.

    • zeroed_removed - [bool]

    • dtmf_removed - [bool]

    • power - [float]

    • dc_level - [float]

    • clipping_rate - [float]

    • dynamic_range -

      • 0[float]

      • 1[float]

    • effective_bits - [int]

    • effective_badwidth -[float]

    • amplitude_factor - [float]

    • lzc_rate - [float]

    • active_lzc_rate - [float]

    • active_clipping_rate - [float]

    • snr - [float]

    • rejected - [bool]

    • rejectd_cause - [str]

Regras de parâmetros

Se o usuário não tiver atingido o min_utterances e/ou o min_speech, receberá uma exceção Caso o usuário passe do definido no max_utterances e/ou no max_speech, o comportamento será determinado pelo modo definido na variável :ref: max_constraint_behavior<max_constraint_behavior>. (consultar o parâmetro para entender seu comportamento).

Exemplo:

Chamada REST enviando o audio via multipart:

curl --request POST \
  --url https://speechd.cpqd.com.br/bio/rest/v2/verify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'verify={
      "repository_uri": "https://speechd.cpqd.com.br/user",
      "min_verification_score": "0.5",
      "id": "<voiceprint_id>"
    }' \
 --form audio=@<path-to-file>/audio1.wav

Exemplo de resposta:

{
  "transaction_id": "bmt-verify-703be44d-e63f-443f-8124-1e18a2174845",
  "voiceprint": [
    {
      "id": "c409358f-38f1-4389-8b58-78bd971a7487",
      "verification": {
        "score": 0.9834442734718323,
        "decision": "ACCEPTED"
      }
    }
  ],
  "audio_info": [
    {
      "audio_duration": 7691,
      "speech_duration": 7271,
      "zeroed_removed": false,
      "dtmf_removed": false,
      "power": -17.628903725058496,
      "dc_level": -0.0000349099313034973,
      "clipping_rate": 0,
      "dynamic_range": [
        -0.6654517077022912,
        0.8049605973607294
      ],
      "effective_bits": 16,
      "effective_bandwidth": 3734.0700414398307,
      "amplitude_factor": 0.4969187328069262,
      "lzc_rate": 0.009102730819245773,
      "active_lzc_rate": 0.009102730819245773,
      "active_clipping_rate": 0,
      "snr": 32.0740550380507,
      "rejected": false
    }
  ]
}