Microsoft Azure Text-Dependent API

swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Text-Dependent API
schemes:
- https
tags:
- name: Text-Dependent
paths:
  /text-dependent/profiles:
    post:
      description: Create a new speaker profile with specified locale.<br>One subscription can create 10,000 speaker profiles at most.
      operationId: microsoftAzureTextdependentCreateprofile
      summary: Microsoft Azure Create Profile
      x-ms-examples:
        Successful Query:
          $ref: ./examples/textDependentCreateProfile.json
      tags:
      - Text-Dependent
      parameters:
      - 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**</li></li></ul>'
        schema:
          required:
          - locale
          $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/TdProfileInfo'
        '400':
          description: 'Bad Request

            * InvalidRequest - Request body is missing.

            * InvalidRequest - Invalid JSON format.

            * InvalidRequest - Locale parameter is missing.

            * InvalidArgument - Invalid locale value. Supported locales are {comma-separated list of locales}.'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              error:
                code: InvalidRequest
                message: Request body is missing.
          x-ms-error-response: true
        '401':
          $ref: '#/responses/Unauthorized'
        '403':
          description: Forbidden - Maximum allowed number of profiles is 10,000.
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              error:
                code: Forbidden
                message: Maximum allowed number of profiles is 10,000.
          x-ms-error-response: true
        '415':
          description: UnsupportedMediaType - Unsupported media type. Only 'application/JSON' is accepted.
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              error:
                code: UnsupportedMediaType
                message: Unsupported media type. Only 'application/JSON' is accepted.
          x-ms-error-response: true
        '429':
          $ref: '#/responses/RateLimit'
        '500':
          $ref: '#/responses/ServerError'
    get:
      x-ms-pageable:
        nextLinkName: '@nextLink'
        itemName: profiles
      description: Retrieves a set of profiles.<br>Profiles are sorted alphabetically by ProfileId
      operationId: microsoftAzureTextdependentListprofiles
      summary: Microsoft Azure List Profiles
      x-ms-examples:
        Successful Query:
          $ref: ./examples/textDependentListProfiles.json
      tags:
      - Text-Dependent
      parameters:
      - in: query
        name: $top
        description: The number of profiles to return. Default is 100 and the maximum is 500
        type: integer
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TdProfileInfoList'
        '400':
          description: 'Bad Request

            * InvalidArgument - Invalid $top parameter value. Value should be positive integer in the range [1, 500].

            * InvalidArgument - Invalid $continuationToken value. $continuationToken must be generated form a prior API call.

            * InvalidArgument - $filter parameter is not supported.

            * InvalidArgument - $skip parameter is not supported.

            * InvalidArgument - $orderBy parameter is not supported.

            * InvalidArgument - $delta parameter is not supported.'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              error:
                code: InvalidArgument
                message: Invalid $top parameter value. Value should be positive integer in the range [1, 500]
          x-ms-error-response: true
        '401':
          $ref: '#/responses/Unauthorized'
        '429':
          $ref: '#/responses/RateLimit'
        '500':
          $ref: '#/responses/ServerError'
  /text-dependent/profiles/{profileId}:
    parameters:
    - $ref: '#/parameters/profileIdParam'
    get:
      description: Retrieves a single profile by ID.
      operationId: microsoftAzureTextdependentGetprofile
      summary: Microsoft Azure Retrieve Single Profile
      x-ms-examples:
        Successful Query:
          $ref: ./examples/textDependentFetchProfile.json
      tags:
      - Text-Dependent
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TdProfileInfo'
        '401':
          $ref: '#/responses/Unauthorized'
        '404':
          $ref: '#/responses/NotFound'
        '429':
          $ref: '#/responses/RateLimit'
        '500':
          $ref: '#/responses/ServerError'
    delete:
      description: Deletes an existing profile.
      operationId: microsoftAzureTextdependentDeleteprofile
      summary: Microsoft Azure Delete Profile
      x-ms-examples:
        Successful Query:
          $ref: ./examples/deleteProfile.json
      tags:
      - Text-Dependent
      responses:
        '204':
          description: OK
        '401':
          $ref: '#/responses/Unauthorized'
        '429':
          $ref: '#/responses/RateLimit'
        '500':
          $ref: '#/responses/ServerError'
  /text-dependent/profiles/{profileId}/reset:
    parameters:
    - $ref: '#/parameters/profileIdParam'
    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 remainingEnrollmentsCount to the initial required number.<br>* Removes all associated enrollments from storage.<br>* Removes chosen passphrase association.<br>* Resets value of modelVersion.
      operationId: microsoftAzureTextdependentResetprofile
      summary: Microsoft Azure Reset Profile
      x-ms-examples:
        Successful Query:
          $ref: ./examples/resetProfile.json
      tags:
      - Text-Dependent
      responses:
        '204':
          description: OK
        '401':
          $ref: '#/responses/Unauthorized'
        '404':
          $ref: '#/responses/NotFound'
        '429':
          $ref: '#/responses/RateLimit'
        '500':
          $ref: '#/responses/ServerError'
  /text-dependent/profiles/{profileId}/enrollments:
    parameters:
    - $ref: '#/parameters/profileIdParam'
    post:
      description: Adds an enrollment to existing profile.<br>If the minimum number of requested enrollment audios is reached, a voice print is created.<br>If the voice print was created before, it gets recreated from all existing enrollment audios including the new one.<br><br>Limitations:<br>* Minimum audio input length per request is **1 second**<br>* Maximum audio input length per request is **10 seconds**<br>* Minimum number of enrollments for creating a voiceprint is **3**<br>* Maximum number of enrollments for creating a voiceprint is **50**<br>* Minimum audio Signal-to-noise ratio (SNR) is **10dB**<br><br>Constraints:<br>* First enrollment must match an existing passphrase.<br>* All enrollments after the first one, must use the same passphrase used in the first enrollment.
      operationId: microsoftAzureTextdependentCreateenrollment
      summary: Microsoft Azure Enroll Profile
      x-ms-examples:
        Successful Query:
          $ref: ./examples/textDependentCreateEnrollment.json
      tags:
      - Text-Dependent
      consumes:
      - audio/wav; codecs=audio/pcm
      parameters:
      - 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/TdEnrollmentInfo'
        '400':
          description: 'Bad Request

            * InvalidRequest - Invalid audio length. Maximum allowed length is 10 seconds.

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

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

            * InvalidRequest - Invalid passphrase.

            * InvalidRequest - Audio is too noisy. The minimum allowed Signal-to-noise ratio (SNR) is 10dB.'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              error:
                code: InvalidRequest
                message: Audio is too noisy.
          x-ms-error-response: true
        '401':
          $ref: '#/responses/Unauthorized'
        '403':
          description: 'Forbidden

            * InvalidOperation - Maximum allowed number of enrollments per profile is 50.'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              error:
                code: InvalidOperation
                message: Maximum allowed number of enrollments per profile is 50.
          x-ms-error-response: true
        '404':
          $ref: '#/responses/NotFound'
        '409':
          description: 'Conflict

            * Conflict - Sending concurrent requests on same profile is not allowed.'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              error:
                code: Conflict
                message: Sending concurrent requests on same profile is not allowed.
          x-ms-error-response: true
        '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'
  /text-dependent/profiles/{profileId}/verify:
    parameters:
    - $ref: '#/parameters/profileIdParam'
    post:
      description: Verifies existing profiles against input audio.<br><br>Limitations:<br>* Minimum audio input length per request is **1 second**<br>* Maximum audio input length per request is **10 seconds**<br>* Minimum audio Signal-to-noise ratio (SNR) is **10 dB**
      operationId: microsoftAzureTextdependentVerifyprofile
      summary: Microsoft Azure Verify Profile
      x-ms-examples:
        Successful Query:
          $ref: ./examples/verify.json
      tags:
      - Text-Dependent
      consumes:
      - audio/wav; codecs=audio/pcm
      parameters:
      - 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 is 10 seconds.

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

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

            * InvalidRequest - Audio is too noisy. The minimum allowed Signal-to-noise ratio (SNR) is 10dB.

            * 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'
  /text-dependent/phrases/{locale}:
    parameters:
    - $ref: '#/parameters/localeParam'
    get:
      description: Retrieves list of supported passphrases for a specific locale.
      operationId: microsoftAzureTextdependentListphrases
      summary: Microsoft Azure Pass Phrases
      x-ms-examples:
        Successful Query:
          $ref: ./examples/phrases.json
      tags:
      - Text-Dependent
      responses:
        '200':
          description: OK
          schema:
            items:
              type: string
            example:
            - my voice is my passport verify me
            - my voice is stronger than passwords
        '400':
          description: 'Bad Request

            * InvalidRequest - Locale parameter is missing.

            * InvalidArgument - Invalid locale value. Supported locales are {comma-separated list of locales}.'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              error:
                code: InvalidRequest
                message: Locale parameter is missing.
          x-ms-error-response: true
        '401':
          $ref: '#/responses/Unauthorized'
        '429':
          $ref: '#/responses/RateLimit'
        '500':
          $ref: '#/responses/ServerError'
definitions:
  TdProfileInfo:
    description: Text-Dependent Speaker profile info
    properties:
      profileId:
        $ref: '#/definitions/ProfileId'
      locale:
        $ref: '#/definitions/Locale'
      enrollmentStatus:
        $ref: '#/definitions/EnrollmentStatus'
      createdDateTime:
        $ref: '#/definitions/CreatedDateTime'
      lastUpdatedDateTime:
        $ref: '#/definitions/LastUpdatedDateTime'
      enrollmentsCount:
        $ref: '#/definitions/EnrollmentsCount'
      enrollmentsLength:
        $ref: '#/definitions/EnrollmentsLength'
      enrollmentsSpeechLength:
        $ref: '#/definitions/EnrollmentsSpeechLength'
      remainingEnrollmentsCount:
        $ref: '#/definitions/RemainingEnrollmentsCount'
      modelVersion:
        $ref: '#/definitions/ModelVersion'
  EnrollmentStatus:
    type: string
    description: 'Status representing the current state of the profile. 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
  TdProfileInfoList:
    description: Text-Dependent Speaker profile info list
    properties:
      profiles:
        items:
          $ref: '#/definitions/TdProfileInfo'
      '@nextLink':
        type: string
        example: https://{Endpoint}/text-dependent/profiles?$top=35&$continuationToken=U21pdGg1QmVuOTk5
  CreatedDateTime:
    type: string
    description: Profile creation datetime.
    example: '2015-04-23T18:25:43.41Z'
  EnrollmentsLength:
    type: number
    description: Total length of enrollment audios accepted for this profile in seconds.
    example: 1.83
  Locale:
    type: string
    pattern: ^[a-zA-Z]{2}-?[a-zA-Z]{2}$
    description: Language identifier consisting of a combination of language code and country code.
    x-nullable: false
    example: en-US
  ProfileId:
    type: string
    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).
    format: uuid
    x-nullable: false
    example: 49a36324-fc4b-4387-aa06-090cfbf0064f
  LastUpdatedDateTime:
    type: string
    description: Last datetime when the profile was updated.
    example: '2015-04-23T19:34:51.52Z'
  ModelVersion:
    type: string
    pattern: ^\d{4}-\d{2}-\d{2}$
    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'
  LocaleInfo:
    description: Speaker profile locale
    properties:
      locale:
        $ref: '#/definitions/Locale'
  TdEnrollmentInfo:
    description: Text-Dependent Speaker profile enrollment info
    properties:
      profileId:
        $ref: '#/definitions/ProfileId'
      enrollmentStatus:
        $ref: '#/definitions/EnrollmentStatus'
      enrollmentsCount:
        $ref: '#/definitions/EnrollmentsCount'
      enrollmentsLength:
        $ref: '#/definitions/EnrollmentsLength'
      enrollmentsSpeechLength:
        $ref: '#/definitions/EnrollmentsSpeechLength'
      remainingEnrollmentsCount:
        $ref: '#/definitions/RemainingEnrollmentsCount'
      passPhrase:
        type: string
        description: Passphrase associated with this enrollment.
        example: my voice is my passport verify me
      audioLength:
        type: number
        description: This enrolment audio length in seconds.
        example: 1.83
      audioSpeechLength:
        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
  EnrollmentsSpeechLength:
    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
  Error:
    description: Speaker error message
    required:
    - error
    properties:
      error:
        properties:
          code:
            type: string
          message:
            type: string
  EnrollmentsCount:
    type: integer
    description: Number of enrolment audios accepted for this profile.
    example: 1
  RemainingEnrollmentsCount:
    type: integer
    description: Number of enrollment audios needed to complete profile enrollment.
    example: 2
parameters:
  profileIdParam:
    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
  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
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
  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'