Tuning management

This section contains tuning management proto files.

Notes:

To download Gatekeeper proto files, click download Gatekeeper proto files.
Default values are determined by the gRPC specification. For more information, go to protocol buffers language guide .

tuning_manager_service.proto

TuningManager

This service allows managing calibration models of various types that are used to optimize the system’s algorithm.

gRPC method definitions

gRPC method definitions
Method Name	Request Type	Response Type	Description
CreateCalibrationModel	CreateCalibrationModel Request	CreateCalibrationModel Response	Creates a new calibration model or a new revision of an existing calibration model. The newly created calibration model’s state is INITIALIZING (not ACTIVE). The client should call ValidateCalibrationModelRevision explicitly to validate the integrity of the calibration model and to call ActivateCalibrationModelRevision when it is ready to be used.
UpdateCalibrationModel	UpdateCalibrationModel Request	UpdateCalibrationModel Response	Updates calibration model details.
ValidateCalibrationModelRevision	ValidateCalibrationModelRevision Request	ValidateCalibrationModelRevision Response	Validates the integrity of the calibration model. If validated successfully, the calibration model’s state is set to VALIDATED.
ActivateCalibrationModelRevision	ActivateCalibrationModelRevision Request	ActivateCalibrationModelRevision Response	Activates the specified revision of a calibration model, setting the state to ACTIVE. If a calibration model with the ID already exists, its state is set to INACTIVE.
DeactivateCalibrationModelRevision	DeactivateCalibrationModelRevision Request	DeactivateCalibrationModelRevision Response	Deactivates the active revision of a calibration model, setting the state to INACTIVE.
ListCalibrationModelRevisions	ListCalibrationModelRevisions Request	ListCalibrationModelRevisions Response	Lists calibration models and their revisions. It is possible to filter calibration models by ID and state.
DownloadCalibrationModelRevision	DownloadCalibrationModelRevision Request	DownloadCalibrationModelRevision Response	Returns URL from which the calibration model can be downloaded.

Methods with HTTP bindings

Notes:

REST API responses use the camel case naming convention, such as gkPersonId, but the REST API requests can either use the camel case or snake case naming convention, such as gk_person_id.
The following example displays root prefix and endpoint to build a complete URL, such as https://gatekeeper.api.nuance.com/v1/audios/upload-url:
- Root prefix for API: https://gatekeeper.api.nuance.com
- Endpoint: /v1/audios/upload-url
To know more about root prefixes for API that can be used for different geographies, go to Sites.

CreateCalibrationModel

POST /v1/calibrations

UpdateCalibrationModel

PATCH /v1/calibrations/{calibration_model_id}

ValidateCalibrationModelRevision

PUT /v1/calibrations/revisions/{gk_calibration_model_revision_id.value}:validate

ActivateCalibrationModelRevision

PUT /v1/calibrations/revisions/{gk_calibration_model_revision_id.value}:activate

DeactivateCalibrationModelRevision

PUT /v1/calibrations/revisions/{gk_calibration_model_revision_id.value}:deactivate

ListCalibrationModelRevisions

GET /v1/calibrations/revisions

Lists calibration models and their revisions. It is possible to filter calibration models by ID and state.

For more information, see ListCalibrationModelRevisions.

Endpoint

/v1/calibrations/revisions

Request

https://{gatekeeper_server_uri}/v1/calibrations/revisions?context.gk_scope_id.value=3809e857-f8f6-418b-8954-2de39bd7b0f4&filter.calibration_model_id=automation_20241029002359_308495&field_mask.paths=['details.description']

Response

{
    "status": {
        "statusCode": "OK",
        "statusSubCode": 0,
        "httpTransCode": 0,
        "fieldViolations": [],
        "statusDetails": [],
        "diagnosticDetails": []
    },
    "details": [
        {
            "calibrationModelId": "",
            "type": "CALIBRATION_MODEL_TYPE_UNSPECIFIED",
            "mode": "CALIBRATION_MODEL_MODE_UNSPECIFIED",
            "engineFramework": "",
            "state": "CALIBRATION_MODEL_STATE_UNSPECIFIED",
            "description": "update_automation"
        },
        {
            "calibrationModelId": "",
            "type": "CALIBRATION_MODEL_TYPE_UNSPECIFIED",
            "mode": "CALIBRATION_MODEL_MODE_UNSPECIFIED",
            "engineFramework": "",
            "state": "CALIBRATION_MODEL_STATE_UNSPECIFIED",
            "description": "update_automation"
        },
        {
            "calibrationModelId": "",
            "type": "CALIBRATION_MODEL_TYPE_UNSPECIFIED",
            "mode": "CALIBRATION_MODEL_MODE_UNSPECIFIED",
            "engineFramework": "",
            "state": "CALIBRATION_MODEL_STATE_UNSPECIFIED",
            "description": "update_automation"
        },
        {
            "calibrationModelId": "",
            "type": "CALIBRATION_MODEL_TYPE_UNSPECIFIED",
            "mode": "CALIBRATION_MODEL_MODE_UNSPECIFIED",
            "engineFramework": "",
            "state": "CALIBRATION_MODEL_STATE_UNSPECIFIED",
            "description": "update_automation"
        },
        {
            "calibrationModelId": "",
            "type": "CALIBRATION_MODEL_TYPE_UNSPECIFIED",
            "mode": "CALIBRATION_MODEL_MODE_UNSPECIFIED",
            "engineFramework": "",
            "state": "CALIBRATION_MODEL_STATE_UNSPECIFIED",
            "description": "update_automation"
        },
        {
            "calibrationModelId": "",
            "type": "CALIBRATION_MODEL_TYPE_UNSPECIFIED",
            "mode": "CALIBRATION_MODEL_MODE_UNSPECIFIED",
            "engineFramework": "",
            "state": "CALIBRATION_MODEL_STATE_UNSPECIFIED",
            "description": "update_automation"
        },
        {
            "calibrationModelId": "",
            "type": "CALIBRATION_MODEL_TYPE_UNSPECIFIED",
            "mode": "CALIBRATION_MODEL_MODE_UNSPECIFIED",
            "engineFramework": "",
            "state": "CALIBRATION_MODEL_STATE_UNSPECIFIED",
            "description": "update_automation"
        },
        {
            "calibrationModelId": "",
            "type": "CALIBRATION_MODEL_TYPE_UNSPECIFIED",
            "mode": "CALIBRATION_MODEL_MODE_UNSPECIFIED",
            "engineFramework": "",
            "state": "CALIBRATION_MODEL_STATE_UNSPECIFIED",
            "description": "update_automation"
        },
        {
            "calibrationModelId": "",
            "type": "CALIBRATION_MODEL_TYPE_UNSPECIFIED",
            "mode": "CALIBRATION_MODEL_MODE_UNSPECIFIED",
            "engineFramework": "",
            "state": "CALIBRATION_MODEL_STATE_UNSPECIFIED",
            "description": "automation"
        },
        {
            "calibrationModelId": "",
            "type": "CALIBRATION_MODEL_TYPE_UNSPECIFIED",
            "mode": "CALIBRATION_MODEL_MODE_UNSPECIFIED",
            "engineFramework": "",
            "state": "CALIBRATION_MODEL_STATE_UNSPECIFIED",
            "description": "update_automation"
        }
    ]
}

DownloadCalibrationModelRevision

POST /v1/calibrations/revisions/{gk_calibration_model_revision_id.value}/download-url

calibration_models_messages.proto

ActivateCalibrationModelRevisionRequest

Input message that defines parameters for ActivateCalibrationModelRevision.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Not used

ActivateCalibrationModelRevisionRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
gk_calibration_model_revision_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the calibration model revision.

ActivateCalibrationModelRevisionResponse

Output message that defines parameters returned by ActivateCalibrationModelRevision.

ActivateCalibrationModelRevisionResponse
Field	Type	Description
status	nuance.rpc.Status	General operation status.

CalibrationModelDetailsForCreate

Contains fields that the system uses to create a calibration model entity. Included in CreateCalibrationModelRequest.

CalibrationModelDetailsForCreate
Field	Type	Description
description	string	Calibration model description.

CalibrationModelDetailsForRead

Contains the readable fields of the calibration model. Included in ListCalibrationModelRevisionsResponse.

CalibrationModelDetailsForRead
Field	Type	Description
gk_calibration_model_revision_id	nuance.biosec.v1.UniqueId	Unique ID of the calibration model revision.
calibration_model_id	string	Calibration model ID.
type	CalibrationModelType	Calibration model type.
mode	CalibrationModelMode	Calibration model mode.
engine_framework	string	The name of the engine’s framework that creates the calibration model.
state	CalibrationModelState	The state of the calibration model.
gk_scope_id	nuance.biosec.v1.UniqueId	The scope to which the calibration model belongs.
description	string	Calibration model description.
creation_timestamp	google.protobuf.Timestamp	Date and time of the calibration model’s creation.
modification_timestamp	google.protobuf.Timestamp	Date and time of the calibration model’s last update.

CalibrationModelDetailsForUpdate

Contains the writable fields of the calibration model entity. Included in UpdateCalibrationModelRequest.

CalibrationModelDetailsForUpdate
Field	Type	Description
description	string	Calibration model description.

CalibrationModelFilter

Calibration model filter. Allows filtering by external ID, state,or type.

CalibrationModelFilter
Field	Type	Description
calibration_model_id	string	Filter by the calibration model’s ID. No wildcards allowed. If not set, the search returns all calibration models.
state	repeated CalibrationModelState	Filter by CalibrationModelState. If not set, the search returns calibration models in any state.
type	repeated CalibrationModelType	Filter by the calibration model’s type. If not set, the search returns calibration models of any type.

CreateCalibrationModelRequest

Input message that defines parameters for CreateCalibrationModel.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Not used

CreateCalibrationModelRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
calibration_model_id	string	Mandatory. Calibration model ID.
type	CalibrationModelType	Mandatory. Calibration model type.
details	CalibrationModelDetailsForCreate	Optional. Additional information about the calibration model.
field_mask	google.protobuf.FieldMask	Optional. A field mask to specify the fields that the method sets.

CreateCalibrationModelResponse

Output message that defines parameters returned by CreateCalibrationModel.

CreateCalibrationModelResponse
Field	Type	Description
status	nuance.rpc.Status	General operation status.
calibration_model_upload_url	string	URL for uploading the calibration model.
gk_calibration_model_revision_id	nuance.biosec.v1.UniqueId	Unique ID of the calibration model revision.

DeactivateCalibrationModelRevisionRequest

Input message that defines parameters for DeactivateCalibrationModelRevision.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Not used

DeactivateCalibrationModelRevisionRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
gk_calibration_model_revision_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the calibration model revision.

DeactivateCalibrationModelRevisionResponse

Output message that defines parameters returned by DeactivateCalibrationModelRevision.

DeactivateCalibrationModelRevisionResponse
Field	Type	Description
status	nuance.rpc.Status	General operation status.

DownloadCalibrationModelRevisionRequest

Input message that defines parameters for DownloadCalibrationModelRevision.

Uses the context field as follows:

gk_engagement_id: Not used
gk_session_id: Not used
gk_scope_id: Mandatory
configset_id: Not used

DownloadCalibrationModelRevisionRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
gk_calibration_model_revision_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the calibration model revision to be downloaded.

DownloadCalibrationModelRevisionResponse

Output message that defines parameters returned by DownloadCalibrationModelRevision.

DownloadCalibrationModelRevisionResponse
Field	Type	Description
status	nuance.rpc.Status	General operation status.
calibration_model_download_url	string	A URL from which the calibration model can be downloaded.

ListCalibrationModelRevisionsRequest

Input message that defines parameters for ListCalibrationModelRevisions.

Uses the context field as follows:

gk_engagement_id: Not used
gk_session_id: Not used
gk_scope_id: Mandatory
configset_id: Not used

ListCalibrationModelRevisionsRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
filter	CalibrationModelFilter	Optional. Filter that limits the list to a specific (external) ID, state or calibration model type.
field_mask	google.protobuf.FieldMask	Optional. A field mask used to specify the CalibrationModelDetailsForRead fields that the method reads.

ListCalibrationModelRevisionsResponse

Output message that defines parameters returned by ListCalibrationModelRevisions. The list is ordered by the creation timestamp in the descending order.

ListCalibrationModelRevisionsResponse
Field	Type	Description
status	nuance.rpc.Status	General operation status.
details	repeated CalibrationModelDetailsForRead	List of calibration model and its metadata attributes.

UpdateCalibrationModelRequest

Input message that defines parameters for UpdateCalibrationModel.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Not used

UpdateCalibrationModelRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
calibration_model_id	string	Mandatory. Calibration model ID.
details	CalibrationModelDetailsForUpdate	Mandatory. Details that the method updates.
field_mask	google.protobuf.FieldMask	Mandatory. A field mask to specify the fields that the method sets.

UpdateCalibrationModelResponse

Output message that defines parameters returned by UpdateCalibrationModel.

UpdateCalibrationModelResponse
Field	Type	Description
status	nuance.rpc.Status	General operation status.

ValidateCalibrationModelRevisionRequest

Input message that defines parameters for ValidateCalibrationModelRevision.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Mandatory

ValidateCalibrationModelRevisionRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
gk_calibration_model_revision_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the calibration model revision.

ValidateCalibrationModelRevisionResponse

Output message that defines parameters returned by ValidateCalibrationModelRevision.

ValidateCalibrationModelRevisionResponse
Field	Type	Description
status	nuance.rpc.Status	General operation status. Contains the list of validation errors.

tuning_manager_enums.proto

CalibrationModelMode

Name	Number	Description
CALIBRATION_MODEL_MODE_UNSPECIFIED	0	Mode is not set.
CALIBRATION_MODEL_MODE_FACTORY	1	Factory calibration model. This model is shared by all scopes and cannot be edited or removed.
CALIBRATION_MODEL_MODE_BASIC	2	Calibration model is a basic calibration.
CALIBRATION_MODEL_MODE_EXTENDED	3	Calibration model is an extended calibration.

CalibrationModelState

Calibration model state. Only active calibration models are used when creating new voiceprints. Inactive calibration models can still be used if the voiceprint is not updated.

Name	Number	Description
CALIBRATION_MODEL_STATE_UNSPECIFIED	0	State is not set.
CALIBRATION_MODEL_STATE_INITIALIZING	1	Calibration model entity is created, but awaits for the model itself to be uploaded and validated.
CALIBRATION_MODEL_STATE_VALIDATED	2	Calibration model is validated.
CALIBRATION_MODEL_STATE_INVALID	3	Calibration model failed validation. Invalid calibration model cannot be activated.
CALIBRATION_MODEL_STATE_ACTIVE	4	Calibration model is activated.
CALIBRATION_MODEL_STATE_INACTIVE	5	Calibration model is explicitly deactivated or another revision of the calibration model is activated.

CalibrationModelType

Calibration model type.

Name	Number	Description
CALIBRATION_MODEL_TYPE_UNSPECIFIED	0	Type is not set.
CALIBRATION_MODEL_TYPE_VOICEPRINTS	1	Calibration model for voiceprint processing operations.
CALIBRATION_MODEL_TYPE_PLAYBACK	2	Calibration model for channel playback detection.
CALIBRATION_MODEL_TYPE_RISK_ENGINE	3	Calibration model for the risk assessment.
CALIBRATION_MODEL_TYPE_CONVOPRINTS	4	Calibration model for convoprint processing operations.
CALIBRATION_MODEL_TYPE_DEVICEPRINTS	5	Calibration model for deviceprint processing operations.