> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/api-rest/identity-api/identity-api-reference/onboarding/voice-enrollment.md).

# Cadastro de voz

Este Endpoint é usado para registrar uma nova voz. Recebe um ou mais arquivos de áudio e retorna uma **template de voz** (voice template). A template de voz é uma string que contém a **informação biométrica da voz**. Esse template pode ser usado para **autenticar vozes no futuro**. Os áudios podem estar criptografados ou não, e **codificados em Base64**. O template retornado sempre está **criptografada e codificada em Base64**. Aceita 1 áudio ou de 3 a 5 áudios para realizar um enrollment independente de texto ou dependente de texto, respectivamente:

* **1 áudio** para enrollment independente de texto (text-independent).
* **3 a 5 áudios** para enrollment dependente de texto (text-dependent).

#### Formatos de áudio suportados

| Formato          |
| ---------------- |
| WAV              |
| MP3              |
| Opus/OGG         |
| AAC              |
| WMA              |
| PCM ulaw e mulaw |
| FLAC             |
| ALAC (mov)       |
| MP4              |
| AIFF             |

### Endpoint

```
POST /voice/enrollment
```

### Cabeçalhos

| Nome          | Tipo   | Obrigatório | Descrição                                                     |
| ------------- | ------ | ----------- | ------------------------------------------------------------- |
| **x-api-key** | string | **Sim**     | API Key de autorização de acesso.                             |
| **family**    | string | Não         | Valor: **Onboarding**. Obrigatório com o serviço de Tracking. |

{% hint style="info" %}
Todas as chamadas aos Endpoints para Tracking com **Identity Platform** devem conter o cabeçalho `family`.
{% endhint %}

### Corpo da solicitação

**Content-Type:** `application/json`

#### Parâmetros

| Parâmetro | Tipo      | Obrigatório | Descrição                                                                                                                                                                 |
| --------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `audios`  | string\[] | **Sim**     | Array de strings. Cada posição do array é um buffer de áudio raw **codificado em Base64** (RFC4648). Máximo de dois arquivos. Aceita **1 áudio**, ou de **3 a 5 áudios**. |

#### Exemplo de solicitação

```json
{
  "audios": ["JVBERi0xLjQKJeLjz9MKNSAwIG9iago8P..."]
}
```

### Respostas

#### `200` Sucesso

#### Parâmetros de resposta

| Parâmetro                                                                 | Tipo    | Descrição                                                                       |
| ------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------- |
| `serviceResultCode`                                                       | integer | Código de resultado que indica o estado da operação. **200** significa sucesso. |
| `serviceResultLog`                                                        | string  | Mensagem de log relacionada ao resultado da operação.                           |
| `timestamp`                                                               | string  | Data e hora em que a operação foi concluída.                                    |
| `serviceTransactionId`                                                    | string  | ID único de transação para rastrear a operação.                                 |
| `serviceResult.operation_result`                                          | integer | Código de resultado da operação de enrollment.                                  |
| `serviceResult.template`                                                  | string  | Template Biométrico **criptografada e codificada em Base64**.                   |
| `serviceResult.template_type`                                             | string  | Tipo de template gerado: `text-dependent` ou `text-independent`.                |
| `serviceResult.validate_audios_result`                                    | array   | Array com os resultados de **validação de cada áudio** enviado.                 |
| `serviceResult.validate_audios_result[].audio_position`                   | integer | Posição do áudio no array enviado.                                              |
| `serviceResult.validate_audios_result[].matching_score`                   | number  | Pontuação de **correspondência** do áudio (0-1). **1.0 = 100%**.                |
| `serviceResult.validate_audios_result[].multiple_speakers_score_detected` | number  | Pontuação de detecção de **múltiplos falantes**.                                |
| `serviceResult.validate_audios_result[].result_code`                      | integer | Código de resultado individual do áudio.                                        |
| `serviceResult.validate_audios_result[].snr_db_detected`                  | number  | Relação **sinal-ruído** detectada no áudio **(dB)**.                            |
| `serviceResult.validate_audios_result[].speech_length_ms_detected`        | integer | Duração da fala detectada em **milissegundos**.                                 |
| `serviceResult.validate_audios_result[].speech_relative_length_detected`  | number  | Proporção relativa de fala em relação à **duração total** do áudio.             |
| `serviceTime`                                                             | string  | Tempo total de execução do serviço **(milissegundos)**.                         |

#### Código de Resultado do Serviço

O `serviceResultCode` indica o resultado geral da execução do serviço:

| serviceResultCode | Descrição                                                                              | Código HTTP |
| ----------------- | -------------------------------------------------------------------------------------- | ----------- |
| 0                 | A execução do serviço foi bem-sucedida, o módulo processou a solicitação corretamente. | 200         |

#### Exemplo de resposta

```json
{
  "serviceResultCode": 200,
  "serviceResultLog": "Serviço executado com sucesso",
  "timestamp": "2024-07-12T09:43:36Z",
  "serviceTransactionId": "99999999-9999-9999-9999-999999999999",
  "serviceResult": {
    "operation_result": 3,
    "template": "BgEBAQIvimhg/Th98mTNID4BPHKsJsf...",
    "template_type": "text-dependent",
    "validate_audios_result": [
      {
        "audio_position": 0,
        "matching_score": 0.9999997019767761,
        "multiple_speakers_score_detected": -3.4028234663852886e+38,
        "result_code": 3,
        "snr_db_detected": 18.781143188476562,
        "speech_length_ms_detected": 4200,
        "speech_relative_length_detected": 0.65625
      },
      {
        "audio_position": 1,
        "matching_score": 1,
        "multiple_speakers_score_detected": -3.4028234663852886e+38,
        "result_code": 3,
        "snr_db_detected": 17.34685707092285,
        "speech_length_ms_detected": 5000,
        "speech_relative_length_detected": 0.6868131756782532
      },
      {
        "audio_position": 2,
        "matching_score": 1,
        "multiple_speakers_score_detected": -3.4028234663852886e+38,
        "result_code": 3,
        "snr_db_detected": 17.34685707092285,
        "speech_length_ms_detected": 5000,
        "speech_relative_length_detected": 0.6868131756782532
      }
    ]
  },
  "serviceTime": "638"
}
```

#### `400` Requisição inválida

```json
{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}
```

#### `401` Não autorizado

```json
{
  "message": "Unauthorized"
}
```

#### `403` Proibido

```json
{
  "Message": "User is not authorized to access this resource with an explicit deny"
}
```

#### `502` Gateway inválido

```json
{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}
```

#### `504` Gateway Timeout

```json
{
  "message": "Endpoint request timed out"
}
```