Microsoft Azure Text-Dependent API

openapi: 3.2.0
info:
  title: Microsoft Azure Speaker Verification Text Dependent API
  version: '2.0'
  description: 'This API is currently available in:


    * West US - westus.api.cognitive.microsoft.com'
security:
- apiKeyHeader: []
tags:
- name: Text-Dependent
paths:
  /text-dependent/profiles:
    post:
      description: 'Create a new speaker profile with specified locale.

        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
      responses:
        '201':
          description: Speaker profile created successfully. GUID is returned to reference the created profile.
          headers:
            Location:
              description: url location of new resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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}.'
          x-ms-error-response: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: InvalidRequest
                  message: Request body is missing.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden - Maximum allowed number of profiles is 10,000.
          x-ms-error-response: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: Forbidden
                  message: Maximum allowed number of profiles is 10,000.
        '415':
          description: UnsupportedMediaType - Unsupported media type. Only 'application/JSON' is accepted.
          x-ms-error-response: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: UnsupportedMediaType
                  message: Unsupported media type. Only 'application/JSON' is accepted.
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'
      requestBody:
        content:
          application/json:
            schema:
              required:
              - locale
              $ref: '#/components/schemas/LocaleInfo'
        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>'
    get:
      x-ms-pageable:
        nextLinkName: '@nextLink'
        itemName: profiles
      description: 'Retrieves a set of profiles.

        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
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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.'
          x-ms-error-response: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: InvalidArgument
                  message: Invalid $top parameter value. Value should be positive integer in the range [1, 500]
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'
  /text-dependent/profiles/{profileId}:
    parameters:
    - $ref: '#/components/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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TdProfileInfo'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/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: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'
  /text-dependent/profiles/{profileId}/reset:
    parameters:
    - $ref: '#/components/parameters/profileIdParam'
    post:
      description: 'Resets existing profile to its original creation state. The reset operation does the following:

        * Updates enrollmentStatus to Enrolling.

        * Updates lastUpdatedDateTime.

        * Updates enrollmentsCount to 0.

        * Updates enrollmentsLength to 0.

        * Updates enrollmentsSpeechLength to 0.

        * Updates remainingEnrollmentsCount to the initial required number.

        * Removes all associated enrollments from storage.

        * Removes chosen passphrase association.

        * 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: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'
  /text-dependent/profiles/{profileId}/enrollments:
    parameters:
    - $ref: '#/components/parameters/profileIdParam'
    post:
      description: 'Adds an enrollment to existing profile.

        If the minimum number of requested enrollment audios is reached, a voice print is created.

        If the voice print was created before, it gets recreated from all existing enrollment audios including the new one.


        Limitations:

        * Minimum audio input length per request is **1 second**

        * Maximum audio input length per request is **10 seconds**

        * Minimum number of enrollments for creating a voiceprint is **3**

        * Maximum number of enrollments for creating a voiceprint is **50**

        * Minimum audio Signal-to-noise ratio (SNR) is **10dB**


        Constraints:

        * First enrollment must match an existing passphrase.

        * 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
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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.'
          x-ms-error-response: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: InvalidRequest
                  message: Audio is too noisy.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 'Forbidden

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

            * Conflict - Sending concurrent requests on same profile is not allowed.'
          x-ms-error-response: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: Conflict
                  message: Sending concurrent requests on same profile is not allowed.
        '415':
          description: UnsupportedMediaType - Unsupported media type. Only "audio/wav; codecs=audio/pcm" is accepted.
          x-ms-error-response: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: UnsupportedMediaType
                  message: Unsupported media type. Only 'audio/wav; codecs=audio/pcm' is accepted.
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'
      requestBody:
        content:
          audio/wav; codecs=audio/pcm:
            schema:
              type: object
              format: file
        description: Binary audio file. Supported formats are audio/wav; codecs=audio/pcm. Supports audio up to 5MB.
        required: true
  /text-dependent/profiles/{profileId}/verify:
    parameters:
    - $ref: '#/components/parameters/profileIdParam'
    post:
      description: 'Verifies existing profiles against input audio.


        Limitations:

        * Minimum audio input length per request is **1 second**

        * Maximum audio input length per request is **10 seconds**

        * 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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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.'
          x-ms-error-response: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: InvalidRequest
                  message: Profile is not enrolled.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          description: UnsupportedMediaType - Unsupported media type. Only "audio/wav; codecs=audio/pcm" is accepted.
          x-ms-error-response: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: UnsupportedMediaType
                  message: Unsupported media type. Only 'audio/wav; codecs=audio/pcm' is accepted.
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'
      requestBody:
        content:
          audio/wav; codecs=audio/pcm:
            schema:
              type: object
              format: file
        description: Binary audio file. Supported formats are audio/wav; codecs=audio/pcm. Supports audio up to 5MB.
        required: true
  /text-dependent/phrases/{locale}:
    parameters:
    - $ref: '#/components/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
          content:
            application/json:
              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}.'
          x-ms-error-response: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: InvalidRequest
                  message: Locale parameter is missing.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    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'
    CreatedDateTime:
      type: string
      description: Profile creation datetime.
      example: '2015-04-23T18:25:43.41Z'
    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
    EnrollmentsLength:
      type: number
      description: Total length of enrollment audios accepted for this profile in seconds.
      example: 1.83
    TdProfileInfo:
      description: Text-Dependent Speaker profile info
      properties:
        profileId:
          $ref: '#/components/schemas/ProfileId'
        locale:
          $ref: '#/components/schemas/Locale'
        enrollmentStatus:
          $ref: '#/components/schemas/EnrollmentStatus'
        createdDateTime:
          $ref: '#/components/schemas/CreatedDateTime'
        lastUpdatedDateTime:
          $ref: '#/components/schemas/LastUpdatedDateTime'
        enrollmentsCount:
          $ref: '#/components/schemas/EnrollmentsCount'
        enrollmentsLength:
          $ref: '#/components/schemas/EnrollmentsLength'
        enrollmentsSpeechLength:
          $ref: '#/components/schemas/EnrollmentsSpeechLength'
        remainingEnrollmentsCount:
          $ref: '#/components/schemas/RemainingEnrollmentsCount'
        modelVersion:
          $ref: '#/components/schemas/ModelVersion'
    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
      example: 49a36324-fc4b-4387-aa06-090cfbf0064f
    Error:
      description: Speaker error message
      required:
      - error
      properties:
        error:
          properties:
            code:
              type: string
            message:
              type: string
    LocaleInfo:
      description: Speaker profile locale
      properties:
        locale:
          $ref: '#/components/schemas/Locale'
    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.
      example: en-US
    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
    RemainingEnrollmentsCount:
      type: integer
      description: Number of enrollment audios needed to complete profile enrollment.
      example: 2
    LastUpdatedDateTime:
      type: string
      description: Last datetime when the profile was updated.
      example: '2015-04-23T19:34:51.52Z'
    EnrollmentsCount:
      type: integer
      description: Number of enrolment audios accepted for this profile.
      example: 1
    TdProfileInfoList:
      description: Text-Dependent Speaker profile info list
      properties:
        profiles:
          items:
            $ref: '#/components/schemas/TdProfileInfo'
        '@nextLink':
          type: string
          example: https://{Endpoint}/text-dependent/profiles?$top=35&$continuationToken=U21pdGg1QmVuOTk5
    TdEnrollmentInfo:
      description: Text-Dependent Speaker profile enrollment info
      properties:
        profileId:
          $ref: '#/components/schemas/ProfileId'
        enrollmentStatus:
          $ref: '#/components/schemas/EnrollmentStatus'
        enrollmentsCount:
          $ref: '#/components/schemas/EnrollmentsCount'
        enrollmentsLength:
          $ref: '#/components/schemas/EnrollmentsLength'
        enrollmentsSpeechLength:
          $ref: '#/components/schemas/EnrollmentsSpeechLength'
        remainingEnrollmentsCount:
          $ref: '#/components/schemas/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
  responses:
    NotFound:
      description: NotFound - Requested profile doesn't exist
      x-ms-error-response: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: Not Found
              message: Requested profile doesn't exist
    RateLimit:
      description: Rate limit is exceeded.
      x-ms-error-response: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RateLimit
              message: Rate limit is exceeded.
    ServerError:
      description: Internal Server Error.
      x-ms-error-response: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: InternalServerError
              message: Internal Server Error.
    Unauthorized:
      description: Request is not authorized. Make sure subscription key is included and valid.
      x-ms-error-response: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: Unauthorized
              message: Request is not authorized. Make sure subscription key is included and valid.
  parameters:
    profileIdParam:
      in: path
      name: profileId
      required: true
      description: Unique identifier for profile id (guid).
      x-ms-parameter-location: method
      schema:
        type: string
        format: uuid
        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}$
    localeParam:
      in: path
      name: locale
      required: true
      description: A combination of language code and country code.
      x-ms-parameter-location: method
      schema:
        type: string
        pattern: ^[a-zA-Z]{2}-?[a-zA-Z]{2}$
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
x-ms-parameterized-host:
  hostTemplate: '{Endpoint}/speaker/verification/v2.0'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'