Microsoft Azure Text-Independent API

swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Text-Independent API
schemes:
- https
tags:
- name: Text-Independent
paths:
  /text-independent/profiles:
    post:
      description: Creates a new speaker profile with specified locale.
      operationId: microsoftAzureTextindependentCreateprofile
      summary: Microsoft Azure Create Profile
      x-ms-examples:
        Successful Query:
          $ref: ./examples/createProfile.json
      tags:
      - Text-Independent
      parameters:
      - $ref: '#/parameters/apiVersionParam'
      - in: body
        name: profileInfo
        description: 'Provide following detail info when creating a new profile.

          Fields  | Description

          ------- | ------------

          locale  | Locale for the language of this speaker profile. A complete supported locale list is here: <ul><li>**en-US (American English)**</li><li>**es-ES (Castilian Spanish)**</li><li>**fr-FR (Standard French)**</li><li>**zh-CN (Mandarin Chinese)**</li></ul>'
        schema:
          $ref: '#/definitions/LocaleInfo'
      responses:
        '201':
          description: Speaker profile created successfully. GUID is returned to reference the created profile.
          headers:
            location:
              type: string
              description: url location of new resource
          schema:
            $ref: '#/definitions/TiProfileInfo'
        default:
          $ref: '#/responses/SpeakerErrorResponse'
    get:
      x-ms-pageable:
        nextLinkName: nextLink
        itemName: value
      description: Retrieves a set of profiles.<br>Profiles are sorted alphabetically by ProfileId
      operationId: microsoftAzureTextindependentListprofiles
      summary: Microsoft Azure List Profile
      x-ms-examples:
        Successful Query:
          $ref: ./examples/listProfiles.json
      tags:
      - Text-Independent
      parameters:
      - $ref: '#/parameters/apiVersionParam'
      - in: query
        name: maxpagesize
        description: The number of profiles to return. Default is 100 and the maximum is 500
        type: integer
        default: 100
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TiProfileInfoList'
        default:
          $ref: '#/responses/SpeakerErrorResponse'
  /text-independent/profiles/{profileId}:
    parameters:
    - $ref: '#/parameters/profileIdParam_2'
    get:
      description: Retrieves a single profile by ID.
      operationId: microsoftAzureTextindependentGetprofile
      summary: Microsoft Azure Retrieve Single Profile
      x-ms-examples:
        Successful Query:
          $ref: ./examples/fetchProfile.json
      tags:
      - Text-Independent
      parameters:
      - $ref: '#/parameters/apiVersionParam'
      - $ref: '#/parameters/profileIdParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TiProfileInfo'
        default:
          $ref: '#/responses/SpeakerErrorResponse'
    delete:
      description: Deletes an existing profile.
      operationId: microsoftAzureTextindependentDeleteprofile
      summary: Microsoft Azure Delete Profile
      x-ms-examples:
        Successful Query:
          $ref: ./examples/deleteProfile.json
      tags:
      - Text-Independent
      parameters:
      - $ref: '#/parameters/apiVersionParam'
      - $ref: '#/parameters/profileIdParam'
      responses:
        '204':
          description: OK
        default:
          $ref: '#/responses/SpeakerErrorResponse'
  /text-independent/profiles/{profileId}:reset:
    post:
      description: Resets existing profile to its original creation state. The reset operation does the following:<br>* Updates enrollmentStatus to Enrolling.<br>* Updates lastUpdatedDateTime.<br>* Updates enrollmentsCount to 0.<br>* Updates enrollmentsLength to 0.<br>* Updates enrollmentsSpeechLength to 0.<br>* Updates remainingEnrollmentsSpeechLength to the required number.<br>* Removes all associated enrollments from storage.<br>* Removes chosen passphrase association.<br>* Resets value of modelVersion.
      operationId: microsoftAzureTextindependentResetprofile
      summary: Microsoft Azure Reset Profile
      x-ms-examples:
        Successful Query:
          $ref: ./examples/resetProfile.json
      tags:
      - Text-Independent
      parameters:
      - $ref: '#/parameters/apiVersionParam'
      - $ref: '#/parameters/profileIdParam'
      responses:
        '200':
          description: Speaker profile reset successfully. Profile is returned with reset values.
          headers:
            location:
              type: string
              description: url location of the resource
          schema:
            $ref: '#/definitions/TiProfileInfo'
        default:
          $ref: '#/responses/SpeakerErrorResponse'
  /text-independent/profiles/{profileId}/enrollments:
    parameters:
    - $ref: '#/parameters/profileIdParam_2'
    post:
      description: Adds an enrollment to existing profile.<br>The first enrollment must be a predefined activation phrase which can be listed using the /phrases/{locale} api.<br>If the minimum number of requested enrollment audios is reached, a voice print is created.<br>Any further enrollment will be used to improve the voice print.<br><br>Limitations:<br>* Minimum audio input length per request is **1 second**<br>* Maximum audio input length per request is **120 seconds**<br>* Minimum total effective speech length (excluding silence and other non-speech frames) for creating a voiceprint is **20 seconds**<br>  This limitation can be disabled by setting ignoreMinLength to **true**.<br><br>* Maximum total audio input length allowed for creating a voiceprint is **300 seconds**<br>* Minimum audio Signal-to-noise ratio (SNR) is **2dB**
      operationId: microsoftAzureTextindependentCreateenrollment
      summary: Microsoft Azure Enroll Profile
      x-ms-examples:
        Successful Query:
          $ref: ./examples/createEnrollment.json
      tags:
      - Text-Independent
      consumes:
      - audio/wav; codecs=audio/pcm
      parameters:
      - $ref: '#/parameters/apiVersionParam'
      - $ref: '#/parameters/profileIdParam'
      - in: query
        name: ignoreMinLength
        type: boolean
        description: If true, a voice print will be created immediately for this profile regardless of how much speech is supplied or stored. Default is false.
        default: false
      - name: audioData
        in: body
        description: Binary audio file. Supported formats are audio/wav; codecs=audio/pcm. Supports audio up to 5MB.
        required: true
        schema:
          type: object
          format: file
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/TiEnrollmentInfo'
        default:
          $ref: '#/responses/SpeakerErrorResponse'
  /text-independent/profiles:identifySingleSpeaker:
    post:
      description: Identifies who is speaking in input audio among a list of candidate profiles.<br><br>Limitations:<br>* Minimum audio input length is **1 second**<br>* Maximum audio input length is **120 seconds**<br>* Minimum candidate speakers count is **1**<br>* Maximum candidate speakers count is **50**<br>* Minimum effective speech length (excluding silence and other non-speech frames) is **4 seconds**<br>  This limitation can be disabled by setting "ignoreMinLength" to **true**.<br><br>* Minimum audio Signal-to-noise ratio (SNR) is **2dB**
      operationId: microsoftAzureTextindependentIdentifysinglespeaker
      summary: Microsoft Azure Identify Single Speaker Profile
      x-ms-examples:
        Successful Query:
          $ref: ./examples/identifySingleSpeaker.json
      tags:
      - Text-Independent
      consumes:
      - audio/wav; codecs=audio/pcm
      parameters:
      - $ref: '#/parameters/apiVersionParam'
      - in: query
        name: profileIds
        type: array
        items:
          type: string
          format: uuid
        minItems: 1
        maxItems: 50
        required: true
        description: Comma-delimited profile IDs. Maximum supported number is 50 IDs.
      - in: query
        name: ignoreMinLength
        type: boolean
        description: If true, the minimum amount of speech needed for identification is skipped. Default is false.
        default: false
      - name: audioData
        in: body
        description: Binary audio file. Supported formats are audio/wav; codecs=audio/pcm. Supports audio up to 5MB.
        required: true
        schema:
          type: object
          format: file
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/IdentifiedSingleSpeakerInfo'
        default:
          $ref: '#/responses/SpeakerErrorResponse'
  /text-independent/phrases/{locale}:
    get:
      description: Retrieves list of supported passphrases for a specific locale.
      operationId: microsoftAzureTextindependentListactivationphrases
      summary: Microsoft Azure Activation Phrases
      x-ms-examples:
        Successful Query:
          $ref: ./examples/listActivationPhrases.json
      tags:
      - Text-Independent
      parameters:
      - $ref: '#/parameters/apiVersionParam'
      - $ref: '#/parameters/localeParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ActivationPhraseInfo'
        default:
          $ref: '#/responses/SpeakerErrorResponse'
  /text-independent/profiles/{profileId}/reset:
    parameters:
    - $ref: '#/parameters/profileIdParam_2'
    post:
      description: Resets existing profile to its original creation state. The reset operation does the following:<br>* Updates enrollmentStatus to Enrolling.<br>* Updates lastUpdatedDateTime.<br>* Updates enrollmentsCount to 0.<br>* Updates enrollmentsLength to 0.<br>* Updates enrollmentsSpeechLength to 0.<br>* Updates remainingEnrollmentsSpeechLength to the required number.<br>* Removes all associated enrollments from storage.<br>* Removes chosen passphrase association.<br>* Resets value of modelVersion.
      operationId: microsoftAzureTextindependentResetprofile
      summary: Microsoft Azure Reset Profile
      x-ms-examples:
        Successful Query:
          $ref: ./examples/resetProfile.json
      tags:
      - Text-Independent
      responses:
        '204':
          description: OK
        '401':
          $ref: '#/responses/Unauthorized'
        '404':
          $ref: '#/responses/NotFound'
        '429':
          $ref: '#/responses/RateLimit'
        '500':
          $ref: '#/responses/ServerError'
  /text-independent/profiles/{profileId}/verify:
    parameters:
    - $ref: '#/parameters/profileIdParam_2'
    post:
      description: Verifies existing profiles against input audio.<br><br>Limitations:<br>* Minimum audio input length is **1 second**<br>* Maximum audio input length is **120 seconds**<br>* Minimum effective speech length (excluding silence and other "non-speech" frames) is **4 seconds**<br>  This limitation can be disabled by setting "ignoreMinLength" to **true**.<br>* Minimum audio Signal-to-noise ratio (SNR) is **0dB**
      operationId: microsoftAzureTextindependentVerifyprofile
      summary: Microsoft Azure Verify Profile
      x-ms-examples:
        Successful Query:
          $ref: ./examples/verify.json
      tags:
      - Text-Independent
      consumes:
      - audio/wav; codecs=audio/pcm
      parameters:
      - in: query
        name: ignoreMinLength
        type: boolean
        description: If true, a voice print will be created immediately for this profile regardless of how much speech is supplied or stored. Default is false.
      - name: audioData
        in: body
        description: Binary audio file. Supported formats are audio/wav; codecs=audio/pcm. Supports audio up to 5MB.
        required: true
        schema:
          type: object
          format: file
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/RecognitionInfo'
        '400':
          description: 'Bad Request

            * InvalidRequest - Invalid audio length. Maximum allowed length per recognition request is 120 seconds.

            * InvalidRequest - Invalid audio length. Minimum allowed length per recognition request is 1 second.

            * InvalidRequest - Invalid audio format. Supported format is 16Khz 16bit Mono PCM.

            * InvalidArgument - Invalid ignoreMinLength parameter value. Valid values are "true" and "false".

            * InvalidRequest - Profile is not enrolled.'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              error:
                code: InvalidRequest
                message: Profile is not enrolled.
          x-ms-error-response: true
        '401':
          $ref: '#/responses/Unauthorized'
        '404':
          $ref: '#/responses/NotFound'
        '415':
          description: UnsupportedMediaType - Unsupported media type. Only "audio/wav; codecs=audio/pcm" is accepted.
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              error:
                code: UnsupportedMediaType
                message: Unsupported media type. Only 'audio/wav; codecs=audio/pcm' is accepted.
          x-ms-error-response: true
        '429':
          $ref: '#/responses/RateLimit'
        '500':
          $ref: '#/responses/ServerError'
definitions:
  ActivationPhraseInfo:
    description: Activation phrase list
    type: object
    required:
    - value
    properties:
      value:
        type: array
        items:
          type: object
          properties:
            activationPhrase:
              $ref: '#/definitions/ActivationPhrase'
  ProfileStatus:
    type: string
    description: 'Status representing the current state of the profile activation. Available values are:

      * Active: profile is active and can be used if the enrollment status is ''Enrolled''.

      * Inactive: profile has not been activated and an activation phrase must be submitted.'
    enum:
    - Active
    - Inactive
    x-ms-enum:
      name: ProfileStatusType
      modelAsString: false
    example: Inactive
  RemainingEnrollmentsSpeechLengthInSec:
    type: number
    description: Amount of pure speech (which is the amount of audio after removing silence and non-speech segments) needed to complete profile enrollment in seconds.
    example: 18.65
  EnrollmentStatus:
    type: string
    description: 'Status representing the current state of the profile enrollment. Available values are:

      * Enrolling: profile has no voice print and not ready for recognition requests.

      * Training: voice print of profile is being created and can’t be used for recognition at the moment.

      * Enrolled: profile has a voice print and ready for recognition requests.'
    enum:
    - Enrolling
    - Training
    - Enrolled
    x-ms-enum:
      name: TrainingStatusType
      modelAsString: false
    example: Enrolling
  IdentifyInfo:
    description: Identified speaker info
    type: object
    properties:
      profileId:
        type: string
        description: ID of identified of profile. If no candidate is identified as the right speaker, the value is set to empty GUID.
        example: 111f427c-3791-468f-b709-fcef7660fff9
        format: uuid
        x-nullable: false
      score:
        type: number
        description: A float number indicating the similarity between input audio and targeted voice print. This number must be between 0 and 1. A higher number means higher similarity.
        example: 0.63
  CreatedDateTime:
    type: string
    format: date-time
    description: Profile creation datetime.
    example: '2015-04-23T18:25:43.41Z'
  Locale:
    type: string
    pattern: ^[a-zA-Z]{2}-?[a-zA-Z]{2}$
    x-nullable: false
    description: Language identifier consisting of a combination of language code and country code.
    example: en-US
  ActivationPhrase:
    type: string
    description: Activation phrases available to activate a profile.
    example: this is my activation phrase to identify me
  ProfileId:
    type: string
    description: Unique identifier for profile id (guid).
    format: uuid
    x-nullable: false
    example: 49a36324-fc4b-4387-aa06-090cfbf0064f
  EnrollmentsLengthInSec:
    type: number
    description: Total length of enrollment audios accepted for this profile in seconds.
    example: 1.83
  EnrollmentsSpeechLengthInSec:
    type: number
    description: Summation of pure speech (which is the amount of audio after removing silence and non-speech segments) across all profile enrollments in seconds.
    example: 1.35
  LastUpdatedDateTime:
    type: string
    format: date-time
    description: Last datetime when the profile was updated.
    example: '2015-04-23T19:34:51.52Z'
  ModelVersion:
    type: string
    format: date
    description: Date specifying the model assigned to this profile. Format is yyyy-mm-dd. If profile has no enrollments, this value will be empty.
    example: '2019-12-05'
  TiProfileInfo:
    description: Text-Independent Speaker profile info
    type: object
    properties:
      profileId:
        $ref: '#/definitions/ProfileId'
      locale:
        $ref: '#/definitions/Locale'
      profileStatus:
        $ref: '#/definitions/ProfileStatus'
      enrollmentStatus:
        $ref: '#/definitions/EnrollmentStatus'
      createdDateTime:
        $ref: '#/definitions/CreatedDateTime'
      lastUpdatedDateTime:
        $ref: '#/definitions/LastUpdatedDateTime'
      enrollmentsCount:
        $ref: '#/definitions/EnrollmentsCount'
      enrollmentsLengthInSec:
        $ref: '#/definitions/EnrollmentsLengthInSec'
      enrollmentsSpeechLengthInSec:
        $ref: '#/definitions/EnrollmentsSpeechLengthInSec'
      remainingEnrollmentsSpeechLengthInSec:
        $ref: '#/definitions/RemainingEnrollmentsSpeechLengthInSec'
      modelVersion:
        $ref: '#/definitions/ModelVersion'
  LocaleInfo:
    description: Speaker profile locale
    type: object
    required:
    - locale
    properties:
      locale:
        $ref: '#/definitions/Locale'
  SpeakerErrorInfo:
    description: Speaker error message
    type: object
    required:
    - error
    properties:
      error:
        required:
        - code
        - message
        type: object
        properties:
          code:
            type: string
          message:
            type: string
  TiEnrollmentInfo:
    description: Speaker profile enrollment info
    type: object
    properties:
      profileId:
        $ref: '#/definitions/ProfileId'
      enrollmentStatus:
        $ref: '#/definitions/EnrollmentStatus'
      enrollmentsCount:
        $ref: '#/definitions/EnrollmentsCount'
      enrollmentsLengthInSec:
        $ref: '#/definitions/EnrollmentsLengthInSec'
      enrollmentsSpeechLengthInSec:
        $ref: '#/definitions/EnrollmentsSpeechLengthInSec'
      remainingEnrollmentsSpeechLengthInSec:
        $ref: '#/definitions/RemainingEnrollmentsSpeechLengthInSec'
      audioLengthInSec:
        type: number
        description: This enrollment audio length in seconds.
        example: 1.83
      audioSpeechLengthInSec:
        type: number
        description: This enrollment audio pure speech (which is the amount of audio after removing silence and non-speech segments) length in seconds.
        example: 1.35
  RecognitionInfo:
    description: Speaker recognition result
    properties:
      recognitionResult:
        type: string
        description: Does audio belong to targeted profile?
        enum:
        - accept
        - reject
        x-ms-enum:
          name: ResultType
          modelAsString: false
        example: Accept
      score:
        type: number
        description: A float number indicating the similarity between input audio and targeted voice print. This number must be between 0 and 1. A higher number means higher similarity.
        example: 0.63
  IdentifiedSingleSpeakerInfo:
    type: object
    properties:
      identifiedProfile:
        description: Object containing data of identified profile.
        $ref: '#/definitions/IdentifyInfo'
      profilesRanking:
        description: Object containing data of the top 5 profiles (including identified profile) sorted in descending order by score.
        type: array
        items:
          $ref: '#/definitions/IdentifyInfo'
        example:
        - profileId: 111f427c-3791-468f-b709-fcef7660fff9
          score: 0.63
        - profileId: 3669fa29-1bf3-45ad-beea-6b348d058d7e
          score: 0.49
        - profileId: 0e196cd9-32d5-4883-8631-54a0e7c7cb3d
          score: 0.4
        - profileId: 726e57d9-04e0-4214-b482-7f786fa83560
          score: 0.1
        - profileId: f95189fd-1bf5-4485-9c2e-e5897e0c98ca
          score: 0.03
  Error:
    description: Speaker error message
    required:
    - error
    properties:
      error:
        properties:
          code:
            type: string
          message:
            type: string
  EnrollmentsCount:
    type: integer
    description: Number of enrollment audios accepted for this profile.
    example: 1
  TiProfileInfoList:
    description: Text-Independent Speaker profile info list
    type: object
    required:
    - value
    properties:
      value:
        type: array
        items:
          $ref: '#/definitions/TiProfileInfo'
      nextLink:
        type: string
        example: '{opaqueUrl}'
parameters:
  profileIdParam:
    in: path
    name: profileId
    required: true
    type: string
    format: uuid
    x-nullable: false
    description: Unique identifier for profile id (guid).
    x-ms-parameter-location: method
  apiVersionParam:
    name: api-version
    x-ms-parameter-location: client
    in: query
    required: true
    type: string
    description: Specifies the version of the operation to use for this request.
    enum:
    - '2021-09-05'
    default: '2021-09-05'
  localeParam:
    in: path
    name: locale
    required: true
    type: string
    x-nullable: false
    pattern: ^[a-zA-Z]{2}-?[a-zA-Z]{2}$
    description: A combination of language code and country code.
    x-ms-parameter-location: method
  profileIdParam_2:
    in: path
    name: profileId
    required: true
    type: string
    format: uuid
    x-nullable: false
    pattern: ^([0-9a-fA-F]){8}-?([0-9a-fA-F]){4}-?([0-9a-fA-F]){4}-?([0-9a-fA-F]){4}-?([0-9a-fA-F]){12}$
    description: Unique identifier for profile id (guid).
    x-ms-parameter-location: method
responses:
  Unauthorized:
    description: Request is not authorized. Make sure subscription key is included and valid.
    schema:
      $ref: '#/definitions/Error'
    examples:
      application/json:
        error:
          code: Unauthorized
          message: Request is not authorized. Make sure subscription key is included and valid.
    x-ms-error-response: true
  RateLimit:
    description: Rate limit is exceeded.
    schema:
      $ref: '#/definitions/Error'
    examples:
      application/json:
        error:
          code: RateLimit
          message: Rate limit is exceeded.
    x-ms-error-response: true
  ServerError:
    description: Internal Server Error.
    schema:
      $ref: '#/definitions/Error'
    examples:
      application/json:
        error:
          code: InternalServerError
          message: Internal Server Error.
    x-ms-error-response: true
  SpeakerErrorResponse:
    description: Failure
    x-ms-error-response: true
    headers:
      x-ms-error-code:
        type: string
        description: Error code
    schema:
      $ref: '#/definitions/SpeakerErrorInfo'
  NotFound:
    description: NotFound - Requested profile doesn't exist
    schema:
      $ref: '#/definitions/Error'
    examples:
      application/json:
        error:
          code: Not Found
          message: Requested profile doesn't exist
    x-ms-error-response: true
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'