> 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/api-rest/identity-api/identity-api-reference/onboarding/voice-enrollment.md).

# Voice Enrollment

Este endpoint se utiliza para registrar una nueva voz. Recibe uno o más archivos de audio y devuelve una **plantilla de voz** (voice template). La plantilla de voz es una cadena que contiene la **información biométrica de la voz**. Esta plantilla puede ser utilizada para **autenticar voces en el futuro**. Los audios pueden estar cifrados o no, y **codificados en Base64**. La plantilla devuelta siempre está **cifrada y codificada en Base64**. Acepta 1 audio, o de 3 a 5 audios, para realizar un enrollment independiente de texto o dependiente de texto, respectivamente:

* **1 audio** para enrollment independiente de texto (text-independent).
* **3 a 5 audios** para enrollment dependiente de texto (text-dependent).

#### Formatos de audio soportados

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

### Endpoint

```
POST /voice/enrollment
```

### Headers

| Nombre        | Tipo   | Requerido | Descripción                                                   |
| ------------- | ------ | --------- | ------------------------------------------------------------- |
| **x-api-key** | string | **Sí**    | API key de autorización de acceso.                            |
| **family**    | string | No        | Valor: **OnBoarding**. Requerido con el servicio de tracking. |

{% hint style="info" %}
Todas las llamadas a los Endpoints para tracking con **Identity Platform** deben contener el header `family`.
{% endhint %}

### Cuerpo de la solicitud

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

#### Parámetros

| Parámetro | Tipo      | Requerido | Descripción                                                                                                                                                             |
| --------- | --------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `audios`  | string\[] | **Sí**    | Array de strings. Cada posición del array es un buffer de audio raw **codificado en Base64** (RFC4648). Máximo dos archivos. Acepta **1 audio**, o de **3 a 5 audios**. |

#### Ejemplo de solicitud

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

### Respuestas

#### `200` Éxito

#### Parámetros de respuesta

| Parámetro                                                                 | Tipo    | Descripción                                                                        |
| ------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------- |
| `serviceResultCode`                                                       | integer | Código de resultado que indica el estado de la operación. **200** significa éxito. |
| `serviceResultLog`                                                        | string  | Mensaje de log relacionado con el resultado de la operación.                       |
| `timestamp`                                                               | string  | Fecha y hora en que se completó la operación.                                      |
| `serviceTransactionId`                                                    | string  | ID único de transacción para rastrear la operación.                                |
| `serviceResult.operation_result`                                          | integer | Código de resultado de la operación de enrollment.                                 |
| `serviceResult.template`                                                  | string  | Plantilla biométrica **cifrada y codificada en Base64**.                           |
| `serviceResult.template_type`                                             | string  | Tipo de plantilla generada: `text-dependent` o `text-independent`.                 |
| `serviceResult.validate_audios_result`                                    | array   | Array con los resultados de **validación de cada audio** enviado.                  |
| `serviceResult.validate_audios_result[].audio_position`                   | integer | Posición del audio en el array enviado.                                            |
| `serviceResult.validate_audios_result[].matching_score`                   | number  | Puntuación de **coincidencia** del audio (0-1). **1.0 = 100%**.                    |
| `serviceResult.validate_audios_result[].multiple_speakers_score_detected` | number  | Puntuación de detección de **múltiples hablantes**.                                |
| `serviceResult.validate_audios_result[].result_code`                      | integer | Código de resultado individual del audio.                                          |
| `serviceResult.validate_audios_result[].snr_db_detected`                  | number  | Relación **señal-ruido** detectada en el audio **(dB)**.                           |
| `serviceResult.validate_audios_result[].speech_length_ms_detected`        | integer | Duración del habla detectada en **milisegundos**.                                  |
| `serviceResult.validate_audios_result[].speech_relative_length_detected`  | number  | Proporción relativa de habla respecto a la **duración total** del audio.           |
| `serviceTime`                                                             | string  | Tiempo total de ejecución del servicio **(milisegundos)**.                         |

#### Service Result Code

El `serviceResultCode` indica el resultado general de la ejecución del servicio:

| serviceResultCode | Descripción                                                                          | Código HTTP |
| ----------------- | ------------------------------------------------------------------------------------ | ----------- |
| 0                 | La ejecución del servicio fue exitosa, el módulo procesó la solicitud correctamente. | 200         |

#### Ejemplo de respuesta

```json
{
  "serviceResultCode": 200,
  "serviceResultLog": "Service executed ok",
  "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` Bad Request

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

#### `401` Unauthorized

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

#### `403` Forbidden

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

#### `502` Bad Gateway

```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"
}
```