Microsoft Azure BatchSynthesis API

openapi: 3.2.0
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Batch Synthesis API
tags:
- name: BatchSynthesis
paths:
  /batchsyntheses:
    get:
      tags:
      - BatchSynthesis
      description: Gets the list of batch syntheses.
      operationId: microsoftAzureBatchsynthesesList
      parameters:
      - $ref: '#/components/parameters/QuerySkip'
      - $ref: '#/components/parameters/QueryMaxPageSize'
      - $ref: '#/components/parameters/QueryApiVersion'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedBatchSynthesis'
        default:
          description: An error occurred.
          headers:
            x-ms-error-code:
              description: Error code
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-pageable:
        nextLinkName: nextLink
        itemName: value
      x-ms-examples:
        Create a project:
          $ref: ./examples/get_batch_syntheses.json
      summary: Microsoft Azure Get Batchsyntheses
  /batchsyntheses/{id}:
    get:
      tags:
      - BatchSynthesis
      description: Gets the batch synthesis identified by the given ID.
      operationId: microsoftAzureBatchsynthesesGet
      parameters:
      - $ref: '#/components/parameters/PathId'
      - $ref: '#/components/parameters/QueryApiVersion'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchSynthesis'
        default:
          description: An error occurred.
          headers:
            x-ms-error-code:
              description: Error code
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        get a batch synthesis job.:
          $ref: ./examples/get_batch_synthesis.json
        get a batch synthesis job with ssml input and user provided container output.:
          $ref: ./examples/get_batch_synthesis_ssml_with_user_provided_container.json
      summary: Microsoft Azure Get Batchsyntheses Id
    put:
      tags:
      - BatchSynthesis
      description: Creates a batch synthesis job, the max allowed payload content length is 500KB.
      operationId: microsoftAzureBatchsynthesesCreate
      parameters:
      - $ref: '#/components/parameters/PathId'
      - in: header
        name: Operation-Id
        required: false
        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.
        schema:
          type: string
          maxLength: 64
          minLength: 3
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$
      - $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 batch synthesis job.
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchSynthesis'
        default:
          description: An error occurred.
          headers:
            x-ms-error-code:
              description: Error code
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-long-running-operation: true
      x-ms-examples:
        Create a batch synthesis job with text input.:
          $ref: ./examples/create_batch_synthesis.json
        Create a batch synthesis job with ssml input and user provided container output.:
          $ref: ./examples/create_batch_synthesis_ssml_with_user_provided_container.json
      summary: Microsoft Azure Put Batchsyntheses Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchSynthesis'
        description: Bath synthesis task definition
        required: true
    delete:
      tags:
      - BatchSynthesis
      description: Deletes the batch synthesis identified by the given ID.
      operationId: microsoftAzureBatchsynthesesDelete
      parameters:
      - $ref: '#/components/parameters/PathId'
      - $ref: '#/components/parameters/QueryApiVersion'
      responses:
        '204':
          description: No Content
        default:
          description: An error occurred.
          headers:
            x-ms-error-code:
              description: Error code
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        get a batch synthesis job.:
          $ref: ./examples/delete_batch_synthesis.json
      summary: Microsoft Azure Delete Batchsyntheses Id
components:
  schemas:
    Error:
      description: New format which conforms to the new Cognitive Services API guidelines which is available at https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow. This contains an outer 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.
          type: string
        message:
          description: High 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'
    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
    BatchSynthesisInput:
      description: Batch Synthesis input.
      required:
      - content
      type: object
      properties:
        content:
          description: It could be SSML or plain text.
          minLength: 1
          type: string
    BatchSynthesis:
      description: Bath synthesis task.
      required:
      - inputKind
      type: object
      properties:
        inputKind:
          $ref: '#/components/schemas/InputKind'
        inputs:
          description: Text or SSML inputs, it's allowed up to 10000 items.
          type: array
          items:
            $ref: '#/components/schemas/BatchSynthesisInput'
        synthesisConfig:
          $ref: '#/components/schemas/BatchSynthesisConfig'
        customVoices:
          description: The custom voice map of voice name and deployment ID.
          type: object
          additionalProperties:
            type: string
            pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$
            minLength: 3
            maxLength: 64
        properties:
          $ref: '#/components/schemas/BatchSynthesisProperties'
        outputs:
          $ref: '#/components/schemas/BatchSynthesisOutputs'
          readOnly: true
        status:
          $ref: '#/components/schemas/Status'
          readOnly: true
        lastActionDateTime:
          description: The time-stamp when the current status was entered.
          format: date-time
          type: string
          readOnly: true
        id:
          $ref: '#/components/schemas/ResourceId'
        description:
          description: The description of the batch synthesis task.
          type: string
        createdDateTime:
          description: The time-stamp when the object was created.
          format: date-time
          type: string
          readOnly: true
    InnerError:
      description: 'New Inner Error format which conforms to Cognitive Services API Guidelines which is available at https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow.

        This contains required properties ErrorCode, 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.
          type: string
        message:
          description: Detailed error message.
          type: string
        innererror:
          $ref: '#/components/schemas/InnerError'
    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
    BatchSynthesisError:
      description: Batch Synthesis Error.
      type: object
      properties:
        code:
          description: Top level error code
          type: string
        message:
          description: Error message
          type: string
    BatchSynthesisProperties:
      description: Detailed properties of batch synthesis task.
      type: object
      properties:
        timeToLiveInHours:
          description: 'How long the batch task will be kept in the system after it has completed. Once the batch task reaches the time to live after completion (succeeded or failed) it will be automatically deleted. The longest supported duration is 744 hours (31 days). The default value is 744 hours. '
          type: integer
          format: int32
        outputFormat:
          description: The requested audio output format. Reference https://learn.microsoft.com/azure/ai-services/speech-service/batch-synthesis-properties#batch-synthesis-properties.
          type: string
        concatenateResult:
          description: Whether synthesis result is concatenated.
          type: boolean
        decompressOutputFiles:
          description: Whether synthesis result is decompressed in target container. It only take effect when "destinationContainerUrl" is specified or "BYOS" is configured.
          type: boolean
        wordBoundaryEnabled:
          description: Whether the word boundary output will be generated.
          type: boolean
        sentenceBoundaryEnabled:
          description: Whether the sentence boundary output will be generated.
          type: boolean
        destinationContainerUrl:
          format: uri
          description: The requested destination container. It is an URL with Service adhoc SAS to a writeable container in Azure Blob storage.
          type: string
        destinationPath:
          description: The destination path in destination container, default to null, it only works when "DestinationContainerUrl" is specified, the final path prefix of outputs should be {DestinationPath}/{TaskId}/, or {TaskId} if not specified.
          type: string
        sizeInBytes:
          format: int64
          description: The generated audio size in bytes.
          type: integer
          readOnly: true
        succeededAudioCount:
          format: int32
          description: The number of succeeded audios.
          type: integer
          readOnly: true
        failedAudioCount:
          format: int32
          description: The number of failed audios.
          type: integer
          readOnly: true
        durationInMilliseconds:
          description: The generated audio duration in milliseconds.
          type: integer
          format: int32
          readOnly: true
        billingDetails:
          $ref: '#/components/schemas/BatchSynthesisBillingDetails'
          readOnly: true
        error:
          $ref: '#/components/schemas/BatchSynthesisError'
          readOnly: true
    BatchSynthesisBillingDetails:
      description: Bath synthesis billing details.
      type: object
      properties:
        neuralCharacters:
          format: int64
          description: The number of billable characters for prebuilt neural voices in the input file.
          type: integer
        customNeuralCharacters:
          format: int64
          description: The number of billable characters for custom neural voices in the input file.
          type: integer
        aoaiCharacters:
          format: int64
          description: The number of billable characters for AOAI voices in the input file.
          type: integer
        aoaiHDCharacters:
          format: int64
          description: The number of billable characters for AOAI HD voices in the input file.
          type: integer
        personalVoiceCharacters:
          format: int64
          description: The number of billable characters for personal voices in the input file.
          type: integer
    PaginatedBatchSynthesis:
      description: Paginated batch synthesis task list
      required:
      - value
      type: object
      properties:
        value:
          description: Bath synthesis tasks.
          type: array
          items:
            $ref: '#/components/schemas/BatchSynthesis'
        nextLink:
          description: Link to next page.
          format: uri
          type: string
    BatchSynthesisConfig:
      description: Text-to-speech configuration for plain text input.
      required:
      - voice
      type: object
      properties:
        voice:
          description: Voice name for PlainText input. You can find platform voice list here https://learn.microsoft.com/azure/ai-services/speech-service/language-support?tabs=tts.
          minLength: 1
          type: string
        style:
          description: Style name for PlainText input.
          type: string
        rate:
          description: Speaking rate for PlainText input. For supported values, see https://learn.microsoft.com/azure/ai-services/speech-service/speech-synthesis-markup-voice#adjust-prosody.
          type: string
        pitch:
          description: Pitch for PlainText input. For supported values, see https://learn.microsoft.com/azure/ai-services/speech-service/speech-synthesis-markup-voice#adjust-prosody.
          type: string
        volume:
          description: Volume for PlainText input. For supported values, see https://learn.microsoft.com/azure/ai-services/speech-service/speech-synthesis-markup-voice#adjust-prosody.
          type: string
        backgroundAudio:
          $ref: '#/components/schemas/BatchSynthesisBackgroundAudioDefinition'
    ErrorResponse:
      description: Error response.
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
    BatchSynthesisBackgroundAudioDefinition:
      description: Background audio setting.
      required:
      - src
      type: object
      properties:
        src:
          format: uri
          description: Source of audio file. Reference https://learn.microsoft.com/azure/ai-services/speech-service/speech-synthesis-markup-voice#add-background-audio.
          type: string
        fadein:
          format: int64
          description: The fadein value of background audio. Reference https://learn.microsoft.com/azure/ai-services/speech-service/speech-synthesis-markup-voice#add-background-audio.
          type: integer
        fadeout:
          format: int64
          description: The fadeout value of background audio. Reference https://learn.microsoft.com/azure/ai-services/speech-service/speech-synthesis-markup-voice#add-background-audio.
          type: integer
        volume:
          format: double
          description: The volume value of background audio. Reference https://learn.microsoft.com/azure/ai-services/speech-service/speech-synthesis-markup-voice#add-background-audio.
          type: number
    InputKind:
      description: Input text kind.
      enum:
      - PlainText
      - SSML
      type: string
      x-ms-enum:
        name: InputKind
        modelAsString: true
    BatchSynthesisOutputs:
      description: Batch Synthesis output.
      type: object
      properties:
        result:
          description: sas url of the result file. It would be relative path when "destinationContainerUrl" is specified.
          type: string
        summary:
          description: When BatchSynthesisProperties.decompressOutputFiles is true, job summary file path will be provided here.
          type: string
    Status:
      description: Status of a resource.
      enum:
      - NotStarted
      - Running
      - Succeeded
      - Failed
      type: string
      x-ms-enum:
        name: Status
        modelAsString: true
  parameters:
    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
    QueryMaxPageSize:
      name: maxpagesize
      in: query
      description: The maximum number of result items to include in a single response.
      required: false
      x-ms-parameter-location: method
      schema:
        type: integer
        format: int32
    PathId:
      name: id
      in: path
      description: The id of 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]$
    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
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'