Migrate code from v3.0 to v3.1 of the REST API

  • Article

The Speech to text REST API is used for Batch transcription and custom speech. Changes from version 3.0 to 3.1 are described in the sections below.

Important

Speech to text REST API v3.2 is available in preview. Speech to text REST API v3.1 is generally available. Speech to text REST API v3.0 will be retired on April 1st, 2026. For more information, see the Speech to text REST API v3.0 to v3.1 and v3.1 to v3.2 migration guides.

Base path

You must update the base path in your code from /speechtotext/v3.0 to /speechtotext/v3.1. For example, to get base models in the chinanorth2 region, use https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.1/models/base instead of https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.0/models/base.

Note these other changes:

  • The /models/{id}/copyto operation (includes '/') in version 3.0 is replaced by the /models/{id}:copyto operation (includes ':') in version 3.1.
  • The /webhooks/{id}/ping operation (includes '/') in version 3.0 is replaced by the /webhooks/{id}:ping operation (includes ':') in version 3.1.
  • The /webhooks/{id}/test operation (includes '/') in version 3.0 is replaced by the /webhooks/{id}:test operation (includes ':') in version 3.1.

For more information, see Operation IDs later in this guide.

Batch transcription

Note

Don't use Speech to text REST API v3.0 to retrieve a transcription created via Speech to text REST API v3.1. You'll see an error message such as the following: "The API version cannot be used to access this transcription. Please use API version v3.1 or higher."

In the Transcriptions_Create operation the following three properties are added:

  • The displayFormWordLevelTimestampsEnabled property can be used to enable the reporting of word-level timestamps on the display form of the transcription results. The results are returned in the displayWords property of the transcription file.
  • The diarization property can be used to specify hints for the minimum and maximum number of speaker labels to generate when performing optional diarization (speaker separation). With this feature, the service is now able to generate speaker labels for more than two speakers. To use this property, you must also set the diarizationEnabled property to true. With the v3.1 API, we have increased the number of speakers that can be identified through diarization from the two speakers supported by the v3.0 API. It's recommended to keep the number of speakers under 30 for better performance.
  • The languageIdentification property can be used specify settings for language identification on the input prior to transcription. Up to 10 candidate locales are supported for language identification. The returned transcription includes a new locale property for the recognized language or the locale that you provided.

The filter property is added to the Transcriptions_List, Transcriptions_ListFiles, and Projects_ListTranscriptions operations. The filter expression can be used to select a subset of the available resources. You can filter by displayName, description, createdDateTime, lastActionDateTime, status, and locale. For example: filter=createdDateTime gt 2022-02-01T11:00:00Z

If you use webhook to receive notifications about transcription status, note that the webhooks created via V3.0 API can't receive notifications for V3.1 transcription requests. You need to create a new webhook endpoint via V3.1 API in order to receive notifications for V3.1 transcription requests.

Custom speech

Datasets

The following operations are added for uploading and managing multiple data blocks for a dataset:

To support model adaptation with structured text in markdown data, the Datasets_Create operation now supports the LanguageMarkdown data kind. For more information, see upload datasets.

Models

The Models_ListBaseModels and Models_GetBaseModel operations return information on the type of adaptation supported by each base model.

"features": {
    "supportsAdaptationsWith": [
        "Acoustic",
        "Language",
        "LanguageMarkdown",
        "Pronunciation"
    ]
}

The Models_Create operation has a new customModelWeightPercent property where you can specify the weight used when the Custom Language Model (trained from plain or structured text data) is combined with the Base Language Model. Valid values are integers between 1 and 100. The default value is currently 30.

The filter property is added to the following operations:

The filter expression can be used to select a subset of the available resources. You can filter by displayName, description, createdDateTime, lastActionDateTime, status, locale, and kind. For example: filter=locale eq 'en-US'

Added the Models_ListFiles operation to get the files of the model identified by the given ID.

Added the Models_GetFile operation to get one specific file (identified with fileId) from a model (identified with ID). This lets you retrieve a ModelReport file that provides information on the data processed during training.

Operation IDs

You must update the base path in your code from /speechtotext/v3.0 to /speechtotext/v3.1. For example, to get base models in the chinanorth2 region, use https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.1/models/base instead of https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.0/models/base.

The name of each operationId in version 3.1 is prefixed with the object name. For example, the operationId for "Create Model" changed from CreateModel in version 3.0 to Models_Create in version 3.1.

Path Method Version 3.1 Operation ID Version 3.0 Operation ID
/datasets GET Datasets_List GetDatasets
/datasets POST Datasets_Create CreateDataset
/datasets/{id} DELETE Datasets_Delete DeleteDataset
/datasets/{id} GET Datasets_Get GetDataset
/datasets/{id} PATCH Datasets_Update UpdateDataset
/datasets/{id}/blocks:commit POST Datasets_CommitBlocks Not applicable
/datasets/{id}/blocks GET Datasets_GetBlocks Not applicable
/datasets/{id}/blocks PUT Datasets_UploadBlock Not applicable
/datasets/{id}/files GET Datasets_ListFiles GetDatasetFiles
/datasets/{id}/files/{fileId} GET Datasets_GetFile GetDatasetFile
/datasets/locales GET Datasets_ListSupportedLocales GetSupportedLocalesForDatasets
/datasets/upload POST Datasets_Upload UploadDatasetFromForm
/endpoints GET Endpoints_List GetEndpoints
/endpoints POST Endpoints_Create CreateEndpoint
/endpoints/{id} DELETE Endpoints_Delete DeleteEndpoint
/endpoints/{id} GET Endpoints_Get GetEndpoint
/endpoints/{id} PATCH Endpoints_Update UpdateEndpoint
/endpoints/{id}/files/logs DELETE Endpoints_DeleteLogs DeleteEndpointLogs
/endpoints/{id}/files/logs GET Endpoints_ListLogs GetEndpointLogs
/endpoints/{id}/files/logs/{logId} DELETE Endpoints_DeleteLog DeleteEndpointLog
/endpoints/{id}/files/logs/{logId} GET Endpoints_GetLog GetEndpointLog
/endpoints/base/{locale}/files/logs DELETE Endpoints_DeleteBaseModelLogs DeleteBaseModelLogs
/endpoints/base/{locale}/files/logs GET Endpoints_ListBaseModelLogs GetBaseModelLogs
/endpoints/base/{locale}/files/logs/{logId} DELETE Endpoints_DeleteBaseModelLog DeleteBaseModelLog
/endpoints/base/{locale}/files/logs/{logId} GET Endpoints_GetBaseModelLog GetBaseModelLog
/endpoints/locales GET Endpoints_ListSupportedLocales GetSupportedLocalesForEndpoints
/evaluations GET Evaluations_List GetEvaluations
/evaluations POST Evaluations_Create CreateEvaluation
/evaluations/{id} DELETE Evaluations_Delete DeleteEvaluation
/evaluations/{id} GET Evaluations_Get GetEvaluation
/evaluations/{id} PATCH Evaluations_Update UpdateEvaluation
/evaluations/{id}/files GET Evaluations_ListFiles GetEvaluationFiles
/evaluations/{id}/files/{fileId} GET Evaluations_GetFile GetEvaluationFile
/evaluations/locales GET Evaluations_ListSupportedLocales GetSupportedLocalesForEvaluations
/healthstatus GET HealthStatus_Get GetHealthStatus
/models GET Models_ListCustomModels GetModels
/models POST Models_Create CreateModel
/models/{id}:copyto1 POST Models_CopyTo CopyModelToSubscription
/models/{id} DELETE Models_Delete DeleteModel
/models/{id} GET Models_GetCustomModel GetModel
/models/{id} PATCH Models_Update UpdateModel
/models/{id}/files GET Models_ListFiles Not applicable
/models/{id}/files/{fileId} GET Models_GetFile Not applicable
/models/{id}/manifest GET Models_GetCustomModelManifest GetModelManifest
/models/base GET Models_ListBaseModels GetBaseModels
/models/base/{id} GET Models_GetBaseModel GetBaseModel
/models/base/{id}/manifest GET Models_GetBaseModelManifest GetBaseModelManifest
/models/locales GET Models_ListSupportedLocales GetSupportedLocalesForModels
/projects GET Projects_List GetProjects
/projects POST Projects_Create CreateProject
/projects/{id} DELETE Projects_Delete DeleteProject
/projects/{id} GET Projects_Get GetProject
/projects/{id} PATCH Projects_Update UpdateProject
/projects/{id}/datasets GET Projects_ListDatasets GetDatasetsForProject
/projects/{id}/endpoints GET Projects_ListEndpoints GetEndpointsForProject
/projects/{id}/evaluations GET Projects_ListEvaluations GetEvaluationsForProject
/projects/{id}/models GET Projects_ListModels GetModelsForProject
/projects/{id}/transcriptions GET Projects_ListTranscriptions GetTranscriptionsForProject
/projects/locales GET Projects_ListSupportedLocales GetSupportedProjectLocales
/transcriptions GET Transcriptions_List GetTranscriptions
/transcriptions POST Transcriptions_Create CreateTranscription
/transcriptions/{id} DELETE Transcriptions_Delete DeleteTranscription
/transcriptions/{id} GET Transcriptions_Get GetTranscription
/transcriptions/{id} PATCH Transcriptions_Update UpdateTranscription
/transcriptions/{id}/files GET Transcriptions_ListFiles GetTranscriptionFiles
/transcriptions/{id}/files/{fileId} GET Transcriptions_GetFile GetTranscriptionFile
/transcriptions/locales GET Transcriptions_ListSupportedLocales GetSupportedLocalesForTranscriptions
/webhooks GET WebHooks_List GetHooks
/webhooks POST WebHooks_Create CreateHook
/webhooks/{id}:ping2 POST WebHooks_Ping PingHook
/webhooks/{id}:test3 POST WebHooks_Test TestHook
/webhooks/{id} DELETE WebHooks_Delete DeleteHook
/webhooks/{id} GET WebHooks_Get GetHook
/webhooks/{id} PATCH WebHooks_Update UpdateHook

1 The /models/{id}/copyto operation (includes '/') in version 3.0 is replaced by the /models/{id}:copyto operation (includes ':') in version 3.1.

2 The /webhooks/{id}/ping operation (includes '/') in version 3.0 is replaced by the /webhooks/{id}:ping operation (includes ':') in version 3.1.

3 The /webhooks/{id}/test operation (includes '/') in version 3.0 is replaced by the /webhooks/{id}:test operation (includes ':') in version 3.1.

Next steps