video translation api refresh

Author: eric-urban

articles/ai-services/speech-service/includes/how-to/video-translation/rest.md

@@ -66,14 +66,14 @@ To create a video translation, you need to construct an HTTP PUT request path an
 - Specify `subtitleMaxCharCountPerSegment`: The maximum number of characters allowed per subtitle segment. This is an optional parameter, and you can set it to 30 if you're unsure.
 - Specify `exportSubtitleInVideo`: A boolean value indicating whether to export subtitles in the video. This is an optional parameter, and you can set it to `true` if you want to include subtitles in the video.
 - Specify the `videoFileUrl`: The URL of the video file you want to translate. The video must be in .mp4 format, less than 500 MB, and shorter than 60 minutes. You can upload the video to Azure Blob Storage and use the Blob URL. For testing purposes, you can use the sample video file provided by Microsoft at [https://speechstudioprodpublicsa.blob.core.windows.net/ttsvoice/VideoTranslation/PublicDoc/SampleData/es-ES-TryOutOriginal.mp4](https://speechstudioprodpublicsa.blob.core.windows.net/ttsvoice/VideoTranslation/PublicDoc/SampleData/es-ES-TryOutOriginal.mp4).
-- Specify `Operation-Id`: The `Operation-Id` must be unique for each operation. The operation ID is valid until the translation is deleted. In the example, `My-Operation-Id-1` is used. Replace `My-Operation-Id-1` with an operation ID of your choice. 
-- Specify `translationId`: The `translationId` must be unique. Replace `My-Translation-Id` with a translation ID of your choice.
-- Replace `YourSpeechResourceKey` with your Speech resource key and replace `YourSpeechResourceRegion` with your Speech resource region.
 
-To create a translation, run the following command with the settings as previously described. 
+For authentication and authorization, you need to include the following headers and path IDs in your request:
+- Set the `Operation-Id` header: The `Operation-Id` must be unique for each operation, such as creating each iteration. Replace `Your-Operation-Id` with a unique ID for this operation.
+- Replace `Your-Translation-Id` in the path. The `translationId` must be unique. Replace `Your-Translation-Id` with a translation ID of your choice. You use this ID to refer to the translation in subsequent API calls.
+- Replace `YourSpeechResourceKey` with your Speech resource key and replace `YourSpeechResourceRegion` with your Speech resource region. 
 
 ```azurecli-interactive
-curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" -H "Operation-Id: My-Operation-Id-1" -H "Content-Type: application/json" -d '{
+curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" -H "Operation-Id: Your-Operation-Id-1" -H "Content-Type: application/json" -d '{
   "displayName": "My translation object",
   "description": "My translation object for video translation iterations",
   "input": {
@@ -85,7 +85,7 @@ curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" -H "Operati
     "exportSubtitleInVideo": false,
     "videoFileUrl": "https://speechstudioprodpublicsa.blob.core.windows.net/ttsvoice/VideoTranslation/PublicDoc/SampleData/es-ES-TryOutOriginal.mp4"
   }
-}' "https://YourSpeechResourceRegion.api.cognitive.microsoft.com/videotranslation/translations/My-Translation-Id?api-version=2024-05-20-preview"
+}' "https://YourSpeechResourceRegion.api.cognitive.microsoft.com/videotranslation/translations/Your-Translation-Id?api-version=2024-05-20-preview"
 ```
 
 > [!IMPORTANT]
@@ -105,7 +105,7 @@ You should receive a response body in the following format:
   },
   "status": "NotStarted",
   "lastActionDateTime": "2025-03-06T19:13:35.669Z",
-  "id": "My-Translation-Id",
+  "id": "Your-Translation-Id",
   "displayName": "My translation object",
   "description": "My translation object for video translation iterations",
   "createdDateTime": "2025-03-06T19:13:35.669Z"
@@ -118,26 +118,27 @@ You can use the operation ID that you specified and use the [Get operation by op
 
 To start translating your video or update an iteration for an existing translation, you need to construct an HTTP PUT request path and body according to the following instructions:
 
-- Specify `Operation-Id`: The `Operation-Id` must be unique for each operation, such as creating each iteration. Replace `My-Operation-Id` with a unique ID for this operation.
-- Specify `translationId`: If multiple iterations are performed under a single translation, the translation ID remains unchanged.
-- Specify `iterationId`: The `iterationId` must be unique for each operation. Replace `My-Iteration-Id` with an iteration ID of your choice.
 - Set the required input: Include details like `speakerCount`, `subtitleMaxCharCountPerSegment`,`exportSubtitleInVideo`, or `webvttFile`. No subtitles are embedded in the output video by default. When creating an iteration, if you already specified the optional parameters `speakerCount`, `subtitleMaxCharCountPerSegment`, and `exportSubtitleInVideo` during the creation of translation, you don’t need to specify them again. The values inherit from translation settings. Once these parameters are defined when creating an iteration, the new values override the original settings. 
+- Optionally, you can specify a WebVTT file with subtitles for your original video. The `webvttFile` input parameter isn't required when creating the first iteration. However, [starting from the second iteration](#step-4-create-additional-iterations-optional), you must specify the `webvttFile` parameter in the iteration process.
+
+For authentication and authorization, you need to include the following headers and path IDs in your request:
+- Set the `Operation-Id` header: The `Operation-Id` must be unique for each operation, such as creating each iteration. Replace `Your-Operation-Id` with a unique ID for this operation.
+- Replace `Your-Translation-Id` in the path. Use the same translation ID that you specified when you [created the translation](#step-1-create-a-translation). The translation ID remains unchanged.
+- Specify a new `iterationId` in the path. The iteration ID must be unique for each operation. Replace `Your-Iteration-Id-1` with an iteration ID of your choice.
 - Replace `YourSpeechResourceKey` with your Speech resource key and replace `YourSpeechResourceRegion` with your Speech resource region. 
 
 ```azurecli-interactive
 curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" \
--H "Operation-Id: My-Operation-Id" \
+-H "Operation-Id: Your-Operation-Id" \
 -H "Content-Type: application/json" \
 -d '{
   "input": {
     "subtitleMaxCharCountPerSegment": 30,
     "exportSubtitleInVideo": true
   }
-}' "https://YourSpeechResourceRegion.api.cognitive.microsoft.com/videotranslation/translations/My-Translation-Id/iterations/My-Iteration-Id?api-version=2024-05-20-preview"
+}' "https://YourSpeechResourceRegion.api.cognitive.microsoft.com/videotranslation/translations/Your-Translation-Id/iterations/Your-Iteration-Id-1?api-version=2024-05-20-preview"
 ```
 
-
-
 You should receive a response body in the following format:
 
 ```json
@@ -148,7 +149,7 @@ You should receive a response body in the following format:
   },
   "status": "NotStarted",
   "lastActionDateTime": "2025-03-06T19:15:38.722Z",
-  "id": "My-Iteration-Id",
+  "id": "Your-Iteration-Id",
   "createdDateTime": "2025-03-06T19:15:38.722Z"
 }
 ```
@@ -159,10 +160,10 @@ You can use the operation ID that you specified and use the [Get operation by op
 
 You can download the translated video and subtitles once the iteration status is `Succeeded`. The translated video and subtitles are available in the response body of the [Get an iteration by iteration ID](/rest/api/aiservices/videotranslation/iteration-operations/get-iteration) API.
 
-To retrieve details of a specific iteration by its ID, use the HTTP GET request. Replace `YourSpeechResourceKey` with your Speech resource key,  `YourSpeechResourceRegion` with your Speech resource region, `My-Translation-Id` with the translation ID you want to check,  and `My-Iteration-Id` with the iteration ID you want to check.
+To retrieve details of a specific iteration by its ID, use the HTTP GET request. Replace `YourSpeechResourceKey` with your Speech resource key,  `YourSpeechResourceRegion` with your Speech resource region, `Your-Translation-Id` with the translation ID you want to check,  and `Your-Iteration-Id` with the iteration ID you want to check.
 
 ```azurecli-interactive
-curl -v -X GET -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" "https://YourSpeechResourceRegion.api.cognitive.microsoft.com/videotranslation/translations/My-Translation-Id/iterations/My-Iteration-Id?api-version=2024-05-20-preview"  
+curl -v -X GET -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" "https://YourSpeechResourceRegion.api.cognitive.microsoft.com/videotranslation/translations/Your-Translation-Id/iterations/Your-Iteration-Id?api-version=2024-05-20-preview"  
 ```
 
 You should receive a response body in the following format:
@@ -182,7 +183,7 @@ You should receive a response body in the following format:
   },
   "status": "Succeeded",
   "lastActionDateTime": "2025-03-06T19:17:06.270Z",
-  "id": "My-Iteration-Id-7",
+  "id": "Your-Iteration-Id-7",
   "createdDateTime": "2025-03-06T19:15:38.723Z"
 }
 ```
@@ -530,46 +531,85 @@ WEBVTT
 
 ## Step 4: Create additional iterations (Optional)
 
-You can create additional iterations to improve the translation quality. The process is similar to creating the first iteration. You can specify different settings for the new iteration, such as `speakerCount`, `subtitleMaxCharCountPerSegment`, and `exportSubtitleInVideo`.
+You can create additional iterations to improve the translation quality. The process is similar to creating the first iteration. 
+
+The `webvttFile` parameter isn't required when creating the first iteration. However, starting from the second iteration, you must specify the `webvttFile` parameter in the iteration process. You need to download the webvtt file, make necessary edits, and then upload it to your Azure Blob storage. You need to specify the Blob URL.
+
+To start translating your video or update an iteration for an existing translation, you need to construct an HTTP PUT request path and body according to the following instructions:
+
+- Specify the required `webvttFile` input parameter. The `webvttFile` parameter is required starting from the second iteration. You need to [download the most recent webvtt file](#download-from-the-result-urls), make the desired edits, and then upload it to your Azure Blob storage. You need to specify the Blob URL. The subtitle file can be in WebVTT or JSON format. 
+- Optionally, you can specify new settings for the new iteration, such as `speakerCount`, `subtitleMaxCharCountPerSegment`, and `exportSubtitleInVideo`.
+
+For authentication and authorization, you need to include the following headers and path IDs in your request:
+- Set the `Operation-Id` header: The `Operation-Id` must be unique for each operation, such as creating each iteration. Replace `Your-Operation-Id` with a unique ID for this operation.
+- Replace `Your-Translation-Id` in the path. Use the same translation ID that you specified when you [created the translation](#step-1-create-a-translation). The translation ID remains unchanged.
+- Specify a new `iterationId` in the path. The iteration ID must be unique for each operation. Replace `Your-Iteration-Id-2` with an iteration ID of your choice.
+- Replace `YourSpeechResourceKey` with your Speech resource key and replace `YourSpeechResourceRegion` with your Speech resource region. 
+
+```azurecli-interactive
+curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" \
+-H "Operation-Id: Your-Operation-Id" \
+-H "Content-Type: application/json" \
+-d '{
+  "input": {
+    "webvttFile": {
+      "url": "https://YourBlobStorageUrl/YourWebVTTFile.vtt"
+    }
+  }
+}' "https://YourSpeechResourceRegion.api.cognitive.microsoft.com/videotranslation/translations/Your-Translation-Id/iterations/Your-Iteration-Id-2?api-version=2024-05-20-preview"
+```
 
-The `webvttFile` parameter isn't required when creating the first iteration. However, starting from the second iteration, you must specify the `webvttFile` parameter in the iteration process. You need to download the webvtt file, make necessary edits, and then upload it to your Azure Blob storage. You need to specify the Blob URL in the curl code.
+You should receive a response body in the following format:
 
-The subtitle file can be in WebVTT or JSON format. If you're unsure about how to prepare a WebVTT file, refer to the following sample formats. 
+```json
+{
+  "input": {
+    "webvttFile": {
+      "url": "https://YourBlobStorageUrl/YourWebVTTFile.vtt"
+    }
+  },
+  "status": "NotStarted",
+  "lastActionDateTime": "2025-03-06T19:15:38.722Z",
+  "id": "Your-Iteration-Id-2",
+  "createdDateTime": "2025-03-06T19:15:38.722Z"
+}
+```
 
+You can use the operation ID that you specified and use the [Get operation by operation ID](#get-operation-by-operation-id) API periodically until the returned status is `Succeeded` or `Failed`. This operation allows you to monitor the progress of your creating the iteration process. The status property should progress from `NotStarted` to `Running`, and finally to `Succeeded` or `Failed`. 
 
 ## Get operation by operation ID
 
 Check the status of an operation using its operation ID. The operation ID is unique for each operation, so you can track each operation separately. The operation ID is valid until the translation is deleted.
 
-- Specify the same `Operation-Id` that you used when creating the translation. In the example, `My-Operation-Id-1` is used. Replace `My-Operation-Id-1` with an operation ID of your choice. 
+- Specify the same `Operation-Id` that you used when creating the translation. In the example, `Your-Operation-Id-1` is used. Replace `Your-Operation-Id-1` with an operation ID of your choice. 
 - Replace `YourSpeechResourceKey` with your Speech resource key and replace `YourSpeechResourceRegion` with your Speech resource region.
 
 ```azurecli-interactive
-curl -v -X GET -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" "https://YourSpeechResourceRegion.api.cognitive.microsoft.com/videotranslation/operations/My-Operation-Id-1?api-version=2024-05-20-preview" 
+curl -v -X GET -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" "https://YourSpeechResourceRegion.api.cognitive.microsoft.com/videotranslation/operations/Your-Operation-Id-1?api-version=2024-05-20-preview" 
 ```
 
 You should receive a response body in the following format:
 
 ```json
 {
-  "id": "My-Operation-Id-1",
+  "id": "Your-Operation-Id-1",
   "status": "Running"
 }
 ```
 
 ## Delete a translation by translation ID
 
-Remove a specific translation identified by `translationId`. This operation also removes all iterations associated with this translation. Replace `YourSpeechResourceKey` with your Speech resource key,  `YourSpeechResourceRegion` with your Speech resource region, and `My-Translation-Id` with the translation ID you want to delete. If not deleted manually, the service retains the translation history for up to 31 days.
+Remove a specific translation identified by `translationId`. This operation also removes all iterations associated with this translation. Replace `YourSpeechResourceKey` with your Speech resource key,  `YourSpeechResourceRegion` with your Speech resource region, and `Your-Translation-Id` with the translation ID you want to delete. If not deleted manually, the service retains the translation history for up to 31 days.
 
 ```azurecli-interactive
-curl -v -X DELETE -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" "https://YourSpeechResourceRegion.api.cognitive.microsoft.com/videotranslation/translations/My-Translation-Id?api-version=2024-05-20-preview" 
+curl -v -X DELETE -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" "https://YourSpeechResourceRegion.api.cognitive.microsoft.com/videotranslation/translations/Your-Translation-Id?api-version=2024-05-20-preview" 
 ```
 
 The response headers include `HTTP/1.1 204 No Content` if the delete request was successful.
 
-## Additional information
+## More REST API examples
 
-This section provides curl commands for other API calls that aren't described in detail previously. You can explore each API using the following commands.
+This section provides curl commands for other video translation API calls that aren't described in detail previously. 
 
 ### List translations
 
@@ -581,18 +621,18 @@ curl -v -X GET -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" "https://Yo
 
 ### Get a translation by translation ID
 
-This operation retrieves detailed information about a specific translation, identified by its unique `translationId`. Replace `YourSpeechResourceKey` with your Speech resource key,  `YourSpeechResourceRegion` with your Speech resource region, and `My-Translation-Id` with the translation ID you want to check.
+This operation retrieves detailed information about a specific translation, identified by its unique `translationId`. Replace `YourSpeechResourceKey` with your Speech resource key,  `YourSpeechResourceRegion` with your Speech resource region, and `Your-Translation-Id` with the translation ID you want to check.
 
 ```azurecli-interactive
-curl -v -X GET -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" "https://YourSpeechResourceRegion.api.cognitive.microsoft.com/videotranslation/translations/My-Translation-Id?api-version=2024-05-20-preview" 
+curl -v -X GET -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" "https://YourSpeechResourceRegion.api.cognitive.microsoft.com/videotranslation/translations/Your-Translation-Id?api-version=2024-05-20-preview" 
 ```
 
 ### List iterations
 
-List all iterations for a specific translation. This request lists all iterations without detailed information. Replace `YourSpeechResourceKey` with your Speech resource key,  `YourSpeechResourceRegion` with your Speech resource region, and `My-Translation-Id` with the translation ID you want to check.
+List all iterations for a specific translation. This request lists all iterations without detailed information. Replace `YourSpeechResourceKey` with your Speech resource key,  `YourSpeechResourceRegion` with your Speech resource region, and `Your-Translation-Id` with the translation ID you want to check.
 
 ```azurecli-interactive
-curl -v -X GET -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" "https://YourSpeechResourceRegion.api.cognitive.microsoft.com/videotranslation/translations/My-Translation-Id/iterations?api-version=2024-05-20-preview"  
+curl -v -X GET -H "Ocp-Apim-Subscription-Key: YourSpeechResourceKey" "https://YourSpeechResourceRegion.api.cognitive.microsoft.com/videotranslation/translations/Your-Translation-Id/iterations?api-version=2024-05-20-preview"  
 ```
 
 ## HTTP status codes