Microsoft Azure BatchSynthesis API

swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector BatchSynthesis API
schemes:
- https
tags:
- name: BatchSynthesis
paths:
  /batchsyntheses:
    get:
      tags:
      - BatchSynthesis
      description: Gets the list of batch syntheses.
      operationId: microsoftAzureBatchsynthesesList
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/QuerySkip'
      - $ref: '#/parameters/QueryMaxPageSize'
      - $ref: '#/parameters/QueryApiVersion'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/PaginatedBatchSynthesis'
        default:
          description: An error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
          headers:
            x-ms-error-code:
              type: string
              description: Error code
      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
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/PathId'
      - $ref: '#/parameters/QueryApiVersion'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/BatchSynthesis'
        default:
          description: An error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
          headers:
            x-ms-error-code:
              type: string
              description: Error code
      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
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/PathId'
      - in: body
        name: definition
        required: true
        description: Bath synthesis task definition
        schema:
          $ref: '#/definitions/BatchSynthesis'
      - 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.
        type: string
        pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$
        minLength: 3
        maxLength: 64
      - $ref: '#/parameters/QueryApiVersion'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/BatchSynthesis'
          headers:
            operation-id:
              type: string
              description: ID of the operation.
            operation-location:
              description: The location of the batch synthesis job.
              type: string
              format: uri
        default:
          description: An error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
          headers:
            x-ms-error-code:
              type: string
              description: Error code
      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
    delete:
      tags:
      - BatchSynthesis
      description: Deletes the batch synthesis identified by the given ID.
      operationId: microsoftAzureBatchsynthesesDelete
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/PathId'
      - $ref: '#/parameters/QueryApiVersion'
      responses:
        '204':
          description: No Content
        default:
          description: An error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
          headers:
            x-ms-error-code:
              type: string
              description: Error code
      x-ms-examples:
        get a batch synthesis job.:
          $ref: ./examples/delete_batch_synthesis.json
      summary: Microsoft Azure Delete Batchsyntheses Id
definitions:
  InputKind:
    description: Input text kind.
    enum:
    - PlainText
    - SSML
    type: string
    x-ms-enum:
      name: InputKind
      modelAsString: true
  PaginatedBatchSynthesis:
    description: Paginated batch synthesis task list
    required:
    - value
    type: object
    properties:
      value:
        description: Bath synthesis tasks.
        type: array
        items:
          $ref: '#/definitions/BatchSynthesis'
      nextLink:
        description: Link to next page.
        format: uri
        type: string
  BatchSynthesis:
    description: Bath synthesis task.
    required:
    - inputKind
    type: object
    properties:
      inputKind:
        $ref: '#/definitions/InputKind'
      inputs:
        description: Text or SSML inputs, it's allowed up to 10000 items.
        type: array
        items:
          $ref: '#/definitions/BatchSynthesisInput'
      synthesisConfig:
        $ref: '#/definitions/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: '#/definitions/BatchSynthesisProperties'
      outputs:
        $ref: '#/definitions/BatchSynthesisOutputs'
        readOnly: true
      status:
        $ref: '#/definitions/Status'
        readOnly: true
      lastActionDateTime:
        description: The time-stamp when the current status was entered.
        format: date-time
        type: string
        readOnly: true
      id:
        $ref: '#/definitions/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
  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: '#/definitions/BatchSynthesisBackgroundAudioDefinition'
  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
  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
  Status:
    description: Status of a resource.
    enum:
    - NotStarted
    - Running
    - Succeeded
    - Failed
    type: string
    x-ms-enum:
      name: Status
      modelAsString: true
  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: '#/definitions/BatchSynthesisBillingDetails'
        readOnly: true
      error:
        $ref: '#/definitions/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
  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: '#/definitions/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: '#/definitions/Error'
      innererror:
        $ref: '#/definitions/InnerError'
  BatchSynthesisError:
    description: Batch Synthesis Error.
    type: object
    properties:
      code:
        description: Top level error code
        type: string
      message:
        description: Error message
        type: string
  ErrorResponse:
    description: Error response.
    required:
    - error
    type: object
    properties:
      error:
        $ref: '#/definitions/Error'
  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
  BatchSynthesisInput:
    description: Batch Synthesis input.
    required:
    - content
    type: object
    properties:
      content:
        description: It could be SSML or plain text.
        minLength: 1
        type: string
  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
  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.\r\nThis 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: '#/definitions/InnerError'
parameters:
  QueryMaxPageSize:
    name: maxpagesize
    in: query
    description: The maximum number of result items to include in a single response.
    required: false
    type: integer
    format: int32
    x-ms-parameter-location: method
  PathId:
    name: id
    in: path
    description: The id of resource.
    required: true
    type: string
    pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$
    minLength: 3
    maxLength: 64
    x-ms-parameter-location: method
  QueryApiVersion:
    name: api-version
    in: query
    description: The API version to use for this operation.
    required: true
    type: string
    minLength: 1
    x-ms-parameter-location: method
    x-ms-client-name: apiVersion
  QuerySkip:
    name: skip
    in: query
    description: The number of result items to skip.
    required: false
    type: integer
    format: int32
    default: 0
    x-ms-parameter-location: method
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'