Microsoft Azure PersonalVoice API

openapi: 3.2.0
info:
  title: Microsoft Azure Custom voice Personal Voice API
  description: Custom voice API to create and deploy your voice.
  contact:
    name: Azure AI - Speech Services
    url: https://learn.microsoft.com/azure/ai-services/speech-service/
  version: 2023-12-01-preview
security:
- subscription_key: []
  AADToken: []
tags:
- name: PersonalVoice
paths:
  /personalvoices:
    get:
      tags:
      - PersonalVoice
      description: Gets a list of personal voices for the authenticated Speech service resource.
      operationId: microsoftAzurePersonalvoicesList
      parameters:
      - $ref: '#/components/parameters/QuerySkip'
      - $ref: '#/components/parameters/QueryMaxPageSize'
      - $ref: '#/components/parameters/QueryFilter'
      - $ref: '#/components/parameters/QueryApiVersion'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedPersonalVoices'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-pageable:
        nextLinkName: nextLink
        itemName: value
      x-ms-examples:
        Get all personal voices:
          $ref: ./examples/get_personalvoices.json
      summary: Microsoft Azure Get Personalvoices
  /personalvoices/{id}:
    get:
      tags:
      - PersonalVoice
      description: Gets the personal voice identified by the given ID.
      operationId: microsoftAzurePersonalvoicesGet
      parameters:
      - $ref: '#/components/parameters/PathId'
      - $ref: '#/components/parameters/QueryApiVersion'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalVoice'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Get a personal voice:
          $ref: ./examples/get_personalvoice.json
      summary: Microsoft Azure Get Personalvoices Id
    delete:
      tags:
      - PersonalVoice
      description: Deletes the personal voice identified by the given ID.
      operationId: microsoftAzurePersonalvoicesDelete
      parameters:
      - $ref: '#/components/parameters/PathId'
      - $ref: '#/components/parameters/QueryApiVersion'
      responses:
        '204':
          description: No Content
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Delete a personal voice:
          $ref: ./examples/delete_personalvoice.json
      summary: Microsoft Azure Delete Personalvoices Id
    put:
      tags:
      - PersonalVoice
      description: Creates a new personal voice with audio files in Azure Blob Storage.
      operationId: microsoftAzurePersonalvoicesCreate
      parameters:
      - $ref: '#/components/parameters/HeaderOperationId'
      - $ref: '#/components/parameters/PathId'
      - $ref: '#/components/parameters/QueryApiVersion'
      responses:
        '201':
          description: Created
          headers:
            Operation-Id:
              description: ID of the operation.
              schema:
                type: string
            Operation-Location:
              description: The location of the operation job. Use this URL to monitor operation status.
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalVoice'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-long-running-operation: true
      x-ms-examples:
        Create a personal voice:
          $ref: ./examples/create_personalvoice.json
      summary: Microsoft Azure Put Personalvoices Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonalVoice'
        description: personal voice definition
        required: true
    post:
      tags:
      - PersonalVoice
      description: Creates a new personal voice with audio files in the client.
      operationId: microsoftAzurePersonalvoicesPost
      parameters:
      - $ref: '#/components/parameters/HeaderOperationId'
      - $ref: '#/components/parameters/PathId'
      - $ref: '#/components/parameters/QueryApiVersion'
      responses:
        '201':
          description: Created
          headers:
            Operation-Id:
              description: ID of the operation.
              schema:
                type: string
            Operation-Location:
              description: The location of the operation job. Use this URL to monitor operation status.
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalVoice'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-long-running-operation: true
      x-ms-long-running-operation-options:
        final-state-via: operation-location
      x-ms-examples:
        Create a personal voice:
          $ref: ./examples/create_personalvoice_with_multipart_form.json
      summary: Microsoft Azure Post Personalvoices Id
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                displayName:
                  type: string
                  description: The display name of this model.
                description:
                  type: string
                  description: Optional description of this model.
                projectId:
                  type: string
                  maxLength: 64
                  minLength: 3
                  pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$
                  description: The project ID.
                audioData:
                  type: string
                  description: Audio files.
                  format: binary
                properties:
                  type: string
                  description: properties.
              required:
              - projectId
components:
  schemas:
    PersonalVoiceProperties:
      description: Personal voice properties
      type: object
      properties:
        failureReason:
          $ref: '#/components/schemas/ModelFailureReason'
      readOnly: true
    PersonalVoice:
      description: Personal voice object
      required:
      - projectId
      - consentId
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ResourceId'
        speakerProfileId:
          description: Personal voice speaker profile id. Fill this property in SSML.
          type: string
          format: uuid
          readOnly: true
        displayName:
          description: Display name of personal voice
          minLength: 1
          type: string
        description:
          description: Personal voice description
          type: string
        projectId:
          $ref: '#/components/schemas/ResourceId'
        consentId:
          $ref: '#/components/schemas/ResourceId'
        audios:
          $ref: '#/components/schemas/AzureBlobContentSource'
        properties:
          $ref: '#/components/schemas/PersonalVoiceProperties'
        status:
          $ref: '#/components/schemas/Status'
        createdDateTime:
          description: The timestamp when the object was created. The timestamp is encoded as ISO 8601 date and time format ("YYYY-MM-DDThh:mm:ssZ", see https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations).
          format: date-time
          type: string
          readOnly: true
        lastActionDateTime:
          description: The timestamp when the current status was entered. The timestamp is encoded as ISO 8601 date and time format ("YYYY-MM-DDThh:mm:ssZ", see https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations).
          format: date-time
          type: string
          readOnly: true
    ModelFailureReason:
      description: Model training failure reason
      enum:
      - None
      - InaccessibleCustomerStorage
      - SpeakerVerificationFailed
      - TerminateByUser
      - Internal
      type: string
      x-ms-enum:
        name: ModelFailureReason
        modelAsString: true
    PaginatedPersonalVoices:
      description: Paginated personal voice list
      required:
      - value
      type: object
      properties:
        value:
          description: Personal voice list
          type: array
          items:
            $ref: '#/components/schemas/PersonalVoice'
        nextLink:
          description: Link to next page.
          format: uri
          type: string
    Error:
      description: Top-level error follows Microsoft Azure REST API Guidelines which is available at https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#handling-errors. This contains an top-level error with error code, message, details, target and an inner error with more descriptive details.
      required:
      - code
      - message
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        target:
          description: The source of the error. For example it would be "model" or "model id" in case of invalid model.
          type: string
        message:
          description: Top-level error message.
          type: string
        details:
          description: Additional supportive details regarding the error and/or expected policies.
          type: array
          items:
            $ref: '#/components/schemas/Error'
        innererror:
          $ref: '#/components/schemas/InnerError'
    AzureBlobContentSource:
      description: Azure Blob Storage content. With the examples below, it represents files https://contoso.blob.core.windows.net/voicecontainer/jessica/*.wav
      type: object
      required:
      - containerUrl
      - extensions
      properties:
        containerUrl:
          description: Azure Blob Storage container URL with [SAS](https://learn.microsoft.com/azure/storage/common/storage-sas-overview). Need both read and list permissions.
          type: string
          format: url
          example: https://contoso.blob.core.windows.net/voicecontainer?mySasToken
        prefix:
          description: Blob name prefix.
          type: string
          example: jessica
        extensions:
          description: File name extensions.
          type: array
          items:
            type: string
            example: .wav
    ErrorCode:
      description: Top-level error code
      enum:
      - BadRequest
      - BadArgument
      - Unauthorized
      - Forbidden
      - NotFound
      - UnsupportedMediaType
      - TooManyRequests
      - InternalServerError
      - ServiceUnavailable
      type: string
      x-ms-enum:
        name: ErrorCode
        modelAsString: true
    ResourceId:
      description: Resource id
      type: string
      pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$
      minLength: 3
      maxLength: 64
    ErrorResponse:
      description: Error response follows Microsoft Azure REST API Guidelines which is available at https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#handling-errors.
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
    InnerError:
      description: Inner error follows Microsoft Azure REST API Guidelines which is available at https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#handling-errors. This contains required properties error code, message and optional properties target, inner error(this can be nested).
      type: object
      properties:
        code:
          description: Detailed error code to help diagnostic.
          type: string
        target:
          description: The source of the error. For example it would be "model" or "model id" in case of invalid model.
          type: string
        message:
          description: Detailed error message.
          type: string
        innererror:
          $ref: '#/components/schemas/InnerError'
    Status:
      description: Status of a resource.
      enum:
      - NotStarted
      - Running
      - Succeeded
      - Failed
      - Disabling
      - Disabled
      type: string
      x-ms-enum:
        name: Status
        modelAsString: true
  parameters:
    QuerySkip:
      name: skip
      in: query
      description: The number of result items to skip.
      required: false
      x-ms-parameter-location: method
      schema:
        type: integer
        format: int32
        default: 0
    QueryApiVersion:
      name: api-version
      in: query
      description: The API version to use for this operation.
      required: true
      x-ms-parameter-location: method
      x-ms-client-name: apiVersion
      schema:
        type: string
        minLength: 1
    HeaderOperationId:
      name: Operation-Id
      in: header
      description: ID of the status monitor for the operation. If the Operation-Id header matches an existing operation and the request is not identical to the prior request, it will fail with a 400 Bad Request.
      required: false
      x-ms-parameter-location: method
      schema:
        type: string
        maxLength: 64
        minLength: 3
        pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$
    QueryFilter:
      name: filter
      in: query
      description: "Filter condition.\n  - **Supported properties:** projectId, createdDateTime, locale, kind\n  - **Operators:**\n    - eq, ne are supported for all properties.\n    - gt, ge, lt, le are supported for createdDateTime.\n  - **Example:**\n    - ```filter=projectId eq 'Jessica'``` (filter by project ID)\n    - ```filter=kind eq 'ProfessionalVoice'``` (filter project by kind)\n    - ```filter=locale eq 'en-US'``` (filter training set and model by locale)\n    - ```filter=createdDateTime gt 2022-12-30T23:59:59.99Z``` (filter resource created time after 2023-11-01)"
      required: false
      x-ms-parameter-location: method
      schema:
        type: string
    QueryMaxPageSize:
      name: maxpagesize
      in: query
      description: The maximum number of items to include in a single response.
      required: false
      x-ms-parameter-location: method
      schema:
        type: integer
        format: int32
        default: 100
    PathId:
      name: id
      in: path
      description: The ID of the resource.
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
        maxLength: 64
        minLength: 3
        pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$
  securitySchemes:
    subscription_key:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
      description: Provide your Speech resource key here.
    AADToken:
      type: oauth2
      flows:
        implicit:
          scopes:
            https://cognitiveservices.azure.com/.default: https://cognitiveservices.azure.com/.default
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
      description: These are the [Microsoft identity platform](entra/identity-platform/v2-overview) flows.
x-ms-parameterized-host:
  hostTemplate: '{endpoint}/customvoice'
  useSchemePrefix: false
  parameters:
  - name: endpoint
    in: path
    description: 'Supported Cognitive Services endpoints (protocol and hostname, for example: https://eastus.api.cognitive.microsoft.com).'
    required: true
    type: string