[Cognitive - Custom Speech] REST API Review, new version v3.1-preview.1

[bexxx]

• Service name: Cognitive Services, Custom Speech
• Key contact: Ralf Beckers
• new preview version for existing service
• service is deployed in multiple hero regions

Some existing features have been extended:

• added diarization (speaker separation) to transcription
• added language identification to transcription
• added retrieval of model files
• allow customizing model weights
• added chunked upload session for large file uploads
• added filters for GETs
• exposing capabilities of models

[czubair]

PR forthcoming

[markweitzel]

API Stewardship Board Review Meeting 22-March-22

Discussion / Notes

• Consider using the block blob storage API as the model for the uploadSessions api.
• Change the upload recommendation to 8mb which is the new high throughput limit
• Add operationId to the links
• Document the default value of the customModelWeight to 20.
• Slides

Actions

Next Steps

The team will update the storage section and work off-line with @tg-msft and schedule a review if necessary.

References

Meeting Chat Meeting Recording

Helpful Documentation

• Azure API REST Documentation
• Considerations for Service Design
• REST API Guidelines
• OpenAPI Style Guidelines
• Breaking Changes

_{Note: The Teams channel is internal MS.}

[markweitzel]

API Stewardship Board Review 31-05-22

All minor changes and discussion centered around consistency and where to deviate.

• POST blocks/commit
• consider adding the supported prefix to the dataset name

To resolve the raised comments we did the following two changes:

1. Block commit route: We are now using POST and make the route datasets/{id}/block/commit, returning a 200 as discussed in the meeting. We saw that for datasets, we did not add the links to the new actions (GET blocks, PUT blocks and POST blocks/commit, this has been added too. Additionally, we are now separating the action "commit" with a ":" instead of "/".

2. Exposing the supported datasetkinds: Instead of offering a variety of Booleans with a specific naming scheme as proposed, we are simply returning an array of supported dataset kinds, BUT we renamed the properties to be easier to understand (adaptableWithDatasetKinds -> supportsAdaptationsWith). Example:

$baseModel.properties.features.supportsAdaptationsWith = Array[DatasetKind(enum)] $baseModel.properties.features.supportsTranscriptions (bool) $baseModel.properties.features.supportsEndpoints (bool) $baseModel.properties.features.supportsTranscriptionsOnSpeechContainers (bool)

Developers can then write code like if (baseModel.properties.features.adaptableWithDatasetKinds.Contains(myDataset.Kind) > -1) {...} C# or if ($baseModel.properties.features.adaptableWithDatasetKinds.indexOf("language") > -1) {...} JS if ($baseModel.properties.features.adaptableWithDatasetKinds.includes(myDataset.kind)) {...} JS

Next Steps

✅ API Review Board: Signed Off

References

[Meeting Chat]() Meeting Recording