Azure AI Speech Transcribe API

openapi: 3.2.0
info:
  title: Speech Services API version 2025-10-15 Transcribe API
  description: Speech Services API version 2025-10-15.
  contact:
    name: Cognitive Services - Speech Services
    url: https://learn.microsoft.com/azure/cognitive-services/speech-service/support
  version: '2025-10-15'
security:
- api_key: []
tags:
- name: Transcribe
paths:
  /transcriptions:transcribe:
    post:
      tags:
      - Transcribe
      summary: Synchronous transcription of an audio file
      operationId: Transcriptions_Transcribe
      parameters:
      - $ref: '#/components/parameters/apiVersionQueryParameter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranscribeResult'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        Transcribe an audio file:
          $ref: ./examples/transcribe_file.json
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                audio:
                  type: string
                  format: binary
                  description: The content of the audio file to be transcribed. The audio file must be shorter than 2 hours in audio duration and smaller than 250 MB in size.
                definition:
                  type: string
                  description: Metadata for a transcription request. This field contains a JSON-serialized object of type `TranscribeDefinition`.
components:
  schemas:
    Phrase:
      description: A transcribed phrase.
      required:
      - confidence
      - durationMilliseconds
      - offsetMilliseconds
      - text
      type: object
      properties:
        channel:
          format: int32
          description: The 0-based channel index. Only present if channel separation is enabled.
          type: integer
        speaker:
          format: int32
          description: A unique integer number that is assigned to each speaker detected in the audio without particular order. Only present if speaker diarization is enabled.
          type: integer
        offsetMilliseconds:
          format: int32
          description: The start offset of the phrase in milliseconds.
          type: integer
        durationMilliseconds:
          format: int32
          description: The duration of the phrase in milliseconds.
          type: integer
        text:
          description: The transcribed text of the phrase.
          type: string
        words:
          description: The words that make up the phrase. Only present if word-level timestamps are enabled.
          type: array
          items:
            $ref: '#/components/schemas/Word'
        locale:
          description: The locale of the phrase.
          type: string
        confidence:
          format: float
          description: The confidence value for the phrase.
          type: number
    TranscribeResult:
      description: The result of the transcribe operation.
      required:
      - combinedPhrases
      - durationMilliseconds
      - phrases
      type: object
      properties:
        durationMilliseconds:
          format: int32
          description: The duration of the audio in milliseconds.
          type: integer
        combinedPhrases:
          description: The full transcript for each channel.
          type: array
          items:
            $ref: '#/components/schemas/ChannelCombinedPhrases'
        phrases:
          description: The transcription results segmented into phrases.
          type: array
          items:
            $ref: '#/components/schemas/Phrase'
    Error:
      title: Error
      description: This error type contains an outer error with error code, message, details, target and an inner error with more descriptive details.
      type: object
      properties:
        message:
          description: High level error message.
          type: string
        target:
          description: 'The source of the error.

            For example it would be "documents" or "document id" in case of invalid document.'
          type: string
        innerError:
          $ref: '#/components/schemas/InnerError'
        code:
          $ref: '#/components/schemas/ErrorCode'
        details:
          description: Additional supportive details regarding the error and/or expected policies.
          type: array
          items:
            $ref: '#/components/schemas/Error'
    InnerError:
      title: 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, details(key value pair), inner error(this can be nested).'
      type: object
      properties:
        message:
          description: High level error message.
          type: string
        target:
          description: 'The source of the error.

            For example it would be "documents" or "document id" in case of invalid document.'
          type: string
        innerError:
          $ref: '#/components/schemas/InnerError'
        code:
          $ref: '#/components/schemas/DetailedErrorCode'
        details:
          description: Additional supportive details regarding the error and/or expected policies.
          type: object
          additionalProperties:
            type: string
    DetailedErrorCode:
      title: DetailedErrorCode
      description: Detailed error code enum.
      enum:
      - InvalidParameterValue
      - InvalidRequestBodyFormat
      - EmptyRequest
      - MissingInputRecords
      - InvalidDocument
      - ModelVersionIncorrect
      - InvalidDocumentBatch
      - UnsupportedLanguageCode
      - DataImportFailed
      - InUseViolation
      - InvalidLocale
      - InvalidBaseModel
      - InvalidAdaptationMapping
      - InvalidDataset
      - InvalidTest
      - FailedDataset
      - InvalidModel
      - InvalidTranscription
      - InvalidPayload
      - InvalidParameter
      - EndpointWithoutLogging
      - InvalidPermissions
      - InvalidPrerequisite
      - InvalidProductId
      - InvalidSubscription
      - InvalidProject
      - InvalidProjectKind
      - InvalidRecordingsUri
      - OnlyOneOfUrlsOrContainerOrDataset
      - ExceededNumberOfRecordingsUris
      - InvalidChannels
      - ModelMismatch
      - ProjectGenderMismatch
      - ModelDeprecated
      - ModelExists
      - ModelNotDeployable
      - EndpointNotUpdatable
      - SingleDefaultEndpoint
      - EndpointCannotBeDefault
      - InvalidModelUri
      - SubscriptionNotFound
      - QuotaViolation
      - UnsupportedDelta
      - UnsupportedFilter
      - UnsupportedPagination
      - UnsupportedDynamicConfiguration
      - UnsupportedOrderBy
      - NoUtf8WithBom
      - ModelDeploymentNotCompleteState
      - SkuLimitsExist
      - DeployingFailedModel
      - UnsupportedTimeRange
      - InvalidLogDate
      - InvalidLogId
      - InvalidLogStartTime
      - InvalidLogEndTime
      - InvalidTopForLogs
      - InvalidSkipTokenForLogs
      - DeleteNotAllowed
      - Forbidden
      - DeployNotAllowed
      - UnexpectedError
      - InvalidCollection
      - InvalidCallbackUri
      - InvalidSasValidityDuration
      - InaccessibleCustomerStorage
      - UnsupportedClassBasedAdaptation
      - InvalidWebHookEventKind
      - InvalidTimeToLive
      - InvalidSourceAzureResourceId
      - ModelCopyAuthorizationExpired
      - EndpointLoggingNotSupported
      - NoLanguageIdentified
      - MultipleLanguagesIdentified
      - InvalidAudioFormat
      - BadChannelConfiguration
      - InvalidChannelSpecification
      - AudioLengthLimitExceeded
      - EmptyAudioFile
      type: string
      x-ms-enum:
        name: DetailedErrorCode
        modelAsString: true
        values:
        - value: InvalidParameterValue
          description: Invalid parameter value.
        - value: InvalidRequestBodyFormat
          description: Invalid request body format.
        - value: EmptyRequest
          description: Empty Request.
        - value: MissingInputRecords
          description: Missing Input Records.
        - value: InvalidDocument
          description: Invalid Document.
        - value: ModelVersionIncorrect
          description: Model Version Incorrect.
        - value: InvalidDocumentBatch
          description: Invalid Document Batch.
        - value: UnsupportedLanguageCode
          description: Unsupported language code.
        - value: DataImportFailed
          description: Data import failed.
        - value: InUseViolation
          description: In use violation.
        - value: InvalidLocale
          description: Invalid locale.
        - value: InvalidBaseModel
          description: Invalid base model.
        - value: InvalidAdaptationMapping
          description: Invalid adaptation mapping.
        - value: InvalidDataset
          description: Invalid dataset.
        - value: InvalidTest
          description: Invalid test.
        - value: FailedDataset
          description: Failed dataset.
        - value: InvalidModel
          description: Invalid model.
        - value: InvalidTranscription
          description: Invalid transcription.
        - value: InvalidPayload
          description: Invalid payload.
        - value: InvalidParameter
          description: Invalid parameter.
        - value: EndpointWithoutLogging
          description: Endpoint without logging.
        - value: InvalidPermissions
          description: Invalid permissions.
        - value: InvalidPrerequisite
          description: Invalid prerequisite.
        - value: InvalidProductId
          description: Invalid product id.
        - value: InvalidSubscription
          description: Invalid subscription.
        - value: InvalidProject
          description: Invalid project.
        - value: InvalidProjectKind
          description: Invalid project kind.
        - value: InvalidRecordingsUri
          description: Invalid recordings uri.
        - value: OnlyOneOfUrlsOrContainerOrDataset
          description: Only one of urls or container or dataset.
        - value: ExceededNumberOfRecordingsUris
          description: Exceeded number of recordings uris.
        - value: InvalidChannels
          description: Invalid channels.
        - value: ModelMismatch
          description: Model mismatch.
        - value: ProjectGenderMismatch
          description: Project gender mismatch.
        - value: ModelDeprecated
          description: Model deprecated.
        - value: ModelExists
          description: Model exists.
        - value: ModelNotDeployable
          description: Model not deployable.
        - value: EndpointNotUpdatable
          description: Endpoint not updatable.
        - value: SingleDefaultEndpoint
          description: Single default endpoint.
        - value: EndpointCannotBeDefault
          description: Endpoint cannot be default.
        - value: InvalidModelUri
          description: Invalid model uri.
        - value: SubscriptionNotFound
          description: Subscription not found.
        - value: QuotaViolation
          description: Quota violation.
        - value: UnsupportedDelta
          description: Unsupported delta.
        - value: UnsupportedFilter
          description: Unsupported filter.
        - value: UnsupportedPagination
          description: Unsupported pagination.
        - value: UnsupportedDynamicConfiguration
          description: Unsupported dynamic configuration.
        - value: UnsupportedOrderBy
          description: Unsupported order by.
        - value: NoUtf8WithBom
          description: No utf8 with bom.
        - value: ModelDeploymentNotCompleteState
          description: Model deployment not complete state.
        - value: SkuLimitsExist
          description: Sku limits exist.
        - value: DeployingFailedModel
          description: Deploying failed model.
        - value: UnsupportedTimeRange
          description: Unsupported time range.
        - value: InvalidLogDate
          description: Invalid log date.
        - value: InvalidLogId
          description: Invalid log id.
        - value: InvalidLogStartTime
          description: Invalid log start time.
        - value: InvalidLogEndTime
          description: Invalid log end time.
        - value: InvalidTopForLogs
          description: Invalid top for logs.
        - value: InvalidSkipTokenForLogs
          description: Invalid skip token for logs.
        - value: DeleteNotAllowed
          description: Delete not allowed.
        - value: Forbidden
          description: Forbidden.
        - value: DeployNotAllowed
          description: Deploy not allowed.
        - value: UnexpectedError
          description: Unexpected error.
        - value: InvalidCollection
          description: Invalid collection.
        - value: InvalidCallbackUri
          description: Invalid callback uri.
        - value: InvalidSasValidityDuration
          description: Invalid sas validity duration.
        - value: InaccessibleCustomerStorage
          description: Inaccessible customer storage.
        - value: UnsupportedClassBasedAdaptation
          description: Unsupported class based adaptation.
        - value: InvalidWebHookEventKind
          description: Invalid web hook event kind.
        - value: InvalidTimeToLive
          description: Invalid time to live.
        - value: InvalidSourceAzureResourceId
          description: Invalid source Azure resource ID.
        - value: ModelCopyAuthorizationExpired
          description: Expired ModelCopyAuthorization.
        - value: EndpointLoggingNotSupported
          description: Endpoint logging not supported.
        - value: NoLanguageIdentified
          description: Language Identification did not recognize any language.
        - value: MultipleLanguagesIdentified
          description: Language Identification recognized multiple languages. No dominant language could be determined.
        - value: InvalidAudioFormat
          description: The format of input audio is not supported.
        - value: BadChannelConfiguration
          description: There is a mismatch between audio channels in the data, in the configuration, or the requirements of the application.
        - value: InvalidChannelSpecification
          description: The selection of channels in the transcription request is not supported (e.g., neither 0 nor 1 have been selected.)
        - value: AudioLengthLimitExceeded
          description: The audio file is longer than the maximum allowed duration.
        - value: EmptyAudioFile
          description: The audio file is empty.
    ErrorCode:
      title: ErrorCode
      description: High level error codes.
      enum:
      - InvalidRequest
      - InvalidArgument
      - InternalServerError
      - ServiceUnavailable
      - NotFound
      - PipelineError
      - Conflict
      - InternalCommunicationFailed
      - Forbidden
      - NotAllowed
      - Unauthorized
      - UnsupportedMediaType
      - TooManyRequests
      - UnprocessableEntity
      type: string
      x-ms-enum:
        name: ErrorCode
        modelAsString: true
        values:
        - value: InvalidRequest
          description: Representing the invalid request error code.
        - value: InvalidArgument
          description: Representing the invalid argument error code.
        - value: InternalServerError
          description: Representing the internal server error error code.
        - value: ServiceUnavailable
          description: Representing the service unavailable error code.
        - value: NotFound
          description: Representing the not found error code.
        - value: PipelineError
          description: Representing the pipeline error error code.
        - value: Conflict
          description: Representing the conflict error code.
        - value: InternalCommunicationFailed
          description: Representing the internal communication failed error code.
        - value: Forbidden
          description: Representing the forbidden error code.
        - value: NotAllowed
          description: Representing the not allowed error code.
        - value: Unauthorized
          description: Representing the unauthorized error code.
        - value: UnsupportedMediaType
          description: Representing the unsupported media type error code.
        - value: TooManyRequests
          description: Representing the too many requests error code.
        - value: UnprocessableEntity
          description: Representing the unprocessable entity error code.
    Word:
      description: Time-stamped word in the display form.
      required:
      - durationMilliseconds
      - offsetMilliseconds
      - text
      type: object
      properties:
        text:
          description: The recognized word, including punctuation.
          type: string
        offsetMilliseconds:
          format: int32
          description: The start offset of the word in milliseconds.
          type: integer
        durationMilliseconds:
          format: int32
          description: The duration of the word in milliseconds.
          type: integer
    ChannelCombinedPhrases:
      description: The full transcript per channel.
      required:
      - text
      type: object
      properties:
        channel:
          format: int32
          description: The 0-based channel index. Only present if channel separation is enabled.
          type: integer
        text:
          description: The transcribed text.
          type: string
  parameters:
    apiVersionQueryParameter:
      in: query
      name: api-version
      description: The requested api version.
      required: true
      x-ms-parameter-location: client
      schema:
        type: string
  securitySchemes:
    api_key:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
      description: Provide your cognitive services account key here.
x-ms-parameterized-host:
  hostTemplate: '{endpoint}/speechtotext'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/endpoint'