Skip to content

Commit fda1300

Browse files
eric-urbaneric-urban
committed
Promote REST pivot option
1 parent a6f2a35 commit fda1300

File tree

3 files changed

+96
-99
lines changed

3 files changed

+96
-99
lines changed

‎articles/cognitive-services/Speech-Service/batch-transcription-create.md

Lines changed: 65 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -20,60 +20,6 @@ With batch transcriptions, you submit the [audio data](batch-transcription-audio
2020

2121
## Create a transcription job
2222

23-
::: zone pivot="speech-cli"
24-
25-
To create a transcription, use the `spx batch transcription create` command. Construct the request parameters according to the following instructions:
26-
27-
- Set the required `content` parameter. You can specify either a semi-colon delimited list of individual files, or the URL for an entire container. For more information about Azure blob storage for batch transcription, see [Locate audio files for batch transcription](batch-transcription-audio-data.md).
28-
- Set the required `language` property. This should match the expected locale of the audio data to transcribe. The locale can't be changed later. The Speech CLI `language` parameter corresponds to the `locale` property in the JSON request and response.
29-
- Set the required `name` property. Choose a transcription name that you can refer to later. The transcription name doesn't have to be unique and can be changed later. The Speech CLI `name` parameter corresponds to the `displayName` property in the JSON request and response.
30-
31-
Here's an example Speech CLI command that creates a transcription job:
32-
33-
```azurecli-interactive
34-
spx batch transcription create --api-version v3.1 --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav;https://crbn.us/whatstheweatherlike.wav
35-
```
36-
37-
You should receive a response body in the following format:
38-
39-
```json
40-
{
41-
"self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0",
42-
"model": {
43-
"self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"
44-
},
45-
"links": {
46-
"files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0/files"
47-
},
48-
"properties": {
49-
"diarizationEnabled": false,
50-
"wordLevelTimestampsEnabled": false,
51-
"channels": [
52-
0,
53-
1
54-
],
55-
"punctuationMode": "DictatedAndAutomatic",
56-
"profanityFilterMode": "Masked"
57-
},
58-
"lastActionDateTime": "2022-10-21T14:21:59Z",
59-
"status": "NotStarted",
60-
"createdDateTime": "2022-10-21T14:21:59Z",
61-
"locale": "en-US",
62-
"displayName": "My Transcription",
63-
"description": ""
64-
}
65-
```
66-
67-
The top-level `self` property in the response body is the transcription's URI. Use this URI to get details such as the URI of the transcriptions and transcription report files. You also use this URI to update or delete a transcription.
68-
69-
For Speech CLI help with transcriptions, run the following command:
70-
71-
```azurecli-interactive
72-
spx help batch transcription
73-
```
74-
75-
::: zone-end
76-
7723
::: zone pivot="rest-api"
7824

7925
To create a transcription, use the [Transcriptions_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Create) operation of the [Speech-to-text REST API](rest-speech-to-text.md#transcriptions). Construct the request body according to the following instructions:
@@ -138,18 +84,62 @@ regularly from the service, after you retrieve the results. Alternatively, set t
13884

13985
::: zone-end
14086

141-
## Request configuration options
142-
14387
::: zone pivot="speech-cli"
14488

145-
For Speech CLI help with transcription configuration options, run the following command:
89+
To create a transcription, use the `spx batch transcription create` command. Construct the request parameters according to the following instructions:
90+
91+
- Set the required `content` parameter. You can specify either a semi-colon delimited list of individual files, or the URL for an entire container. For more information about Azure blob storage for batch transcription, see [Locate audio files for batch transcription](batch-transcription-audio-data.md).
92+
- Set the required `language` property. This should match the expected locale of the audio data to transcribe. The locale can't be changed later. The Speech CLI `language` parameter corresponds to the `locale` property in the JSON request and response.
93+
- Set the required `name` property. Choose a transcription name that you can refer to later. The transcription name doesn't have to be unique and can be changed later. The Speech CLI `name` parameter corresponds to the `displayName` property in the JSON request and response.
94+
95+
Here's an example Speech CLI command that creates a transcription job:
14696

14797
```azurecli-interactive
148-
spx help batch transcription create advanced
98+
spx batch transcription create --api-version v3.1 --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav;https://crbn.us/whatstheweatherlike.wav
99+
```
100+
101+
You should receive a response body in the following format:
102+
103+
```json
104+
{
105+
"self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0",
106+
"model": {
107+
"self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"
108+
},
109+
"links": {
110+
"files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0/files"
111+
},
112+
"properties": {
113+
"diarizationEnabled": false,
114+
"wordLevelTimestampsEnabled": false,
115+
"channels": [
116+
0,
117+
1
118+
],
119+
"punctuationMode": "DictatedAndAutomatic",
120+
"profanityFilterMode": "Masked"
121+
},
122+
"lastActionDateTime": "2022-10-21T14:21:59Z",
123+
"status": "NotStarted",
124+
"createdDateTime": "2022-10-21T14:21:59Z",
125+
"locale": "en-US",
126+
"displayName": "My Transcription",
127+
"description": ""
128+
}
129+
```
130+
131+
The top-level `self` property in the response body is the transcription's URI. Use this URI to get details such as the URI of the transcriptions and transcription report files. You also use this URI to update or delete a transcription.
132+
133+
For Speech CLI help with transcriptions, run the following command:
134+
135+
```azurecli-interactive
136+
spx help batch transcription
149137
```
150138

151139
::: zone-end
152140

141+
## Request configuration options
142+
153143
::: zone pivot="rest-api"
154144

155145
Here are some property options that you can use to configure a transcription when you call the [Transcriptions_Create](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Create) operation.
@@ -171,21 +161,22 @@ Here are some property options that you can use to configure a transcription whe
171161

172162
::: zone-end
173163

174-
175-
## Using custom models
176-
177-
Batch transcription uses the default base model for the locale that you specify. You don't need to set any properties to use the default base model.
178-
179-
Optionally, you can modify the previous [create transcription example](#create-a-batch-transcription) by setting the `model` property to use a specific base model or [Custom Speech](how-to-custom-speech-train-model.md) model.
180-
181164
::: zone pivot="speech-cli"
182165

166+
For Speech CLI help with transcription configuration options, run the following command:
167+
183168
```azurecli-interactive
184-
spx batch transcription create --api-version v3.1 --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav;https://crbn.us/whatstheweatherlike.wav --model "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base/1aae1070-7972-47e9-a977-87e3b05c457d"
169+
spx help batch transcription create advanced
185170
```
186171

187172
::: zone-end
188173

174+
## Using custom models
175+
176+
Batch transcription uses the default base model for the locale that you specify. You don't need to set any properties to use the default base model.
177+
178+
Optionally, you can modify the previous [create transcription example](#create-a-batch-transcription) by setting the `model` property to use a specific base model or [Custom Speech](how-to-custom-speech-train-model.md) model.
179+
189180
::: zone pivot="rest-api"
190181

191182
```azurecli-interactive
@@ -207,6 +198,14 @@ curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey" -H "Content-
207198

208199
::: zone-end
209200

201+
::: zone pivot="speech-cli"
202+
203+
```azurecli-interactive
204+
spx batch transcription create --api-version v3.1 --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav;https://crbn.us/whatstheweatherlike.wav --model "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base/1aae1070-7972-47e9-a977-87e3b05c457d"
205+
```
206+
207+
::: zone-end
208+
210209
To use a Custom Speech model for batch transcription, you need the model's URI. You can retrieve the model location when you create or get a model. The top-level `self` property in the response body is the model's URI. For an example, see the JSON response example in the [Create a model](how-to-custom-speech-train-model.md?pivots=rest-api#create-a-model) guide. A [custom model deployment endpoint](how-to-custom-speech-deploy-model.md) isn't needed for the batch transcription service.
211210

212211
Batch transcription requests for expired models will fail with a 4xx error. You'll want to set the `model` property to a base model or custom model that hasn't yet expired. Otherwise don't include the `model` property to always use the latest base model. For more information, see [Choose a model](how-to-custom-speech-create-project.md#choose-your-model) and [Custom Speech model lifecycle](how-to-custom-speech-model-and-endpoint-lifecycle.md).

‎articles/cognitive-services/Speech-Service/batch-transcription-get.md

Lines changed: 27 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -20,16 +20,14 @@ To get transcription results, first check the [status](#get-transcription-status
2020

2121
## Get transcription status
2222

23-
::: zone pivot="speech-cli"
24-
25-
To get the status of the transcription job, use the `spx batch transcription status` command. Construct the request parameters according to the following instructions:
23+
::: zone pivot="rest-api"
2624

27-
- Set the `transcription` parameter to the ID of the transcription that you want to get.
25+
To get the status of the transcription job, call the [Transcriptions_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Get) operation of the [Speech-to-text REST API](rest-speech-to-text.md).
2826

29-
Here's an example Speech CLI command to get the transcription status:
27+
Make an HTTP GET request using the URI as shown in the following example. Replace `YourTranscriptionId` with your transcription ID, replace `YourSubscriptionKey` with your Speech resource key, and replace `YourServiceRegion` with your Speech resource region.
3028

3129
```azurecli-interactive
32-
spx batch transcription status --api-version v3.1 --transcription YourTranscriptionId
30+
curl -v -X GET "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/YourTranscriptionId" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"
3331
```
3432

3533
You should receive a response body in the following format:
@@ -65,22 +63,19 @@ You should receive a response body in the following format:
6563

6664
The `status` property indicates the current status of the transcriptions. The transcriptions and transcription report will be available when the transcription status is `Succeeded`.
6765

68-
For Speech CLI help with transcriptions, run the following command:
69-
70-
```azurecli-interactive
71-
spx help batch transcription
72-
```
7366

7467
::: zone-end
7568

76-
::: zone pivot="rest-api"
69+
::: zone pivot="speech-cli"
7770

78-
To get the status of the transcription job, call the [Transcriptions_Get](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_Get) operation of the [Speech-to-text REST API](rest-speech-to-text.md).
71+
To get the status of the transcription job, use the `spx batch transcription status` command. Construct the request parameters according to the following instructions:
7972

80-
Make an HTTP GET request using the URI as shown in the following example. Replace `YourTranscriptionId` with your transcription ID, replace `YourSubscriptionKey` with your Speech resource key, and replace `YourServiceRegion` with your Speech resource region.
73+
- Set the `transcription` parameter to the ID of the transcription that you want to get.
74+
75+
Here's an example Speech CLI command to get the transcription status:
8176

8277
```azurecli-interactive
83-
curl -v -X GET "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/YourTranscriptionId" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"
78+
spx batch transcription status --api-version v3.1 --transcription YourTranscriptionId
8479
```
8580

8681
You should receive a response body in the following format:
@@ -116,23 +111,25 @@ You should receive a response body in the following format:
116111

117112
The `status` property indicates the current status of the transcriptions. The transcriptions and transcription report will be available when the transcription status is `Succeeded`.
118113

114+
For Speech CLI help with transcriptions, run the following command:
115+
116+
```azurecli-interactive
117+
spx help batch transcription
118+
```
119119

120120
::: zone-end
121121

122122
## Get transcription results
123123

124+
::: zone pivot="rest-api"
124125

125-
::: zone pivot="speech-cli"
126-
127-
The `spx batch transcription list` command returns a list of result files for a transcription. A [transcription report](#transcription-report-file) file is provided for each submitted batch transcription job. In addition, one [transcription](#transcription-result-file) file (the end result) is provided for each successfully transcribed audio file.
128126

129-
- Set the required `files` flag.
130-
- Set the required `transcription` parameter to the ID of the transcription that you want to get logs.
127+
The [Transcriptions_ListFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_ListFiles) operation returns a list of result files for a transcription. A [transcription report](#transcription-report-file) file is provided for each submitted batch transcription job. In addition, one [transcription](#transcription-result-file) file (the end result) is provided for each successfully transcribed audio file.
131128

132-
Here's an example Speech CLI command that gets a list of result files for a transcription:
129+
Make an HTTP GET request using the "files" URI from the previous response body. Replace `YourTranscriptionId` with your transcription ID, replace `YourSubscriptionKey` with your Speech resource key, and replace `YourServiceRegion` with your Speech resource region.
133130

134131
```azurecli-interactive
135-
spx batch transcription list --api-version v3.1 --files --transcription YourTranscriptionId
132+
curl -v -X GET "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/YourTranscriptionId/files" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"
136133
```
137134

138135
You should receive a response body in the following format:
@@ -182,19 +179,21 @@ You should receive a response body in the following format:
182179

183180
The location of each transcription and transcription report files with more details are returned in the response body. The `contentUrl` property contains the URL to the [transcription](#transcription-result-file) (`"kind": "Transcription"`) or [transcription report](#transcription-report-file) (`"kind": "TranscriptionReport"`) file.
184181

185-
By default, the results are stored in a container managed by Microsoft. When the transcription job is deleted, the transcription result data is also deleted.
182+
If you didn't specify a container in the `destinationContainerUrl` property of the transcription request, the results are stored in a container managed by Microsoft. When the transcription job is deleted, the transcription result data is also deleted.
186183

187184
::: zone-end
188185

189-
::: zone pivot="rest-api"
186+
::: zone pivot="speech-cli"
190187

188+
The `spx batch transcription list` command returns a list of result files for a transcription. A [transcription report](#transcription-report-file) file is provided for each submitted batch transcription job. In addition, one [transcription](#transcription-result-file) file (the end result) is provided for each successfully transcribed audio file.
191189

192-
The [Transcriptions_ListFiles](https://eastus.dev.cognitive.microsoft.com/docs/services/speech-to-text-api-v3-1/operations/Transcriptions_ListFiles) operation returns a list of result files for a transcription. A [transcription report](#transcription-report-file) file is provided for each submitted batch transcription job. In addition, one [transcription](#transcription-result-file) file (the end result) is provided for each successfully transcribed audio file.
190+
- Set the required `files` flag.
191+
- Set the required `transcription` parameter to the ID of the transcription that you want to get logs.
193192

194-
Make an HTTP GET request using the "files" URI from the previous response body. Replace `YourTranscriptionId` with your transcription ID, replace `YourSubscriptionKey` with your Speech resource key, and replace `YourServiceRegion` with your Speech resource region.
193+
Here's an example Speech CLI command that gets a list of result files for a transcription:
195194

196195
```azurecli-interactive
197-
curl -v -X GET "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/YourTranscriptionId/files" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"
196+
spx batch transcription list --api-version v3.1 --files --transcription YourTranscriptionId
198197
```
199198

200199
You should receive a response body in the following format:
@@ -244,11 +243,10 @@ You should receive a response body in the following format:
244243

245244
The location of each transcription and transcription report files with more details are returned in the response body. The `contentUrl` property contains the URL to the [transcription](#transcription-result-file) (`"kind": "Transcription"`) or [transcription report](#transcription-report-file) (`"kind": "TranscriptionReport"`) file.
246245

247-
If you didn't specify a container in the `destinationContainerUrl` property of the transcription request, the results are stored in a container managed by Microsoft. When the transcription job is deleted, the transcription result data is also deleted.
246+
By default, the results are stored in a container managed by Microsoft. When the transcription job is deleted, the transcription result data is also deleted.
248247

249248
::: zone-end
250249

251-
252250
### Transcription report file
253251

254252
One transcription report file is provided for each submitted batch transcription job.

‎articles/zone-pivot-groups.yml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -736,19 +736,19 @@ groups:
736736
pivots:
737737
- id: speech-studio
738738
title: Speech Studio
739-
- id: speech-cli
740-
title: CLI
741739
- id: rest-api
742740
title: REST
741+
- id: speech-cli
742+
title: CLI
743743
- id: speech-cli-rest
744744
# Owner: eur
745745
title: Programming languages
746746
prompt: Choose a tool or API
747747
pivots:
748-
- id: speech-cli
749-
title: CLI
750748
- id: rest-api
751749
title: REST
750+
- id: speech-cli
751+
title: CLI
752752
- id: programming-languages-set-nineteen
753753
title: Programming languages
754754
prompt: Choose a programming language

0 commit comments

Comments
 (0)