Update Annotation Set Annotations for Automatic Speech Recognition (ASR) API
Call this API to add or update the annotations for an existing annotation set that you plan to evaluate with the ASR Evaluation tool.
Make sure that you have created a catalog for your upload before uploading your files. For more details about the API call sequence for creating a catalog, creating an annotation set, or populating that annotation set for ASR evaluations, see API Flow.
HTTP method and path
PUT v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}/annotations HTTP/1.1
Parameters
| Field | Type | Description | Required |
|---|---|---|---|
skillId |
String | Skill Id as part of the URI path. | Yes |
annotationSetId |
String | Annotation Id as part of the URI path. | Yes |
Request
Request headers
Content-Type: [application/json, text/csv]
Accept: application/json
| Field | Type | Description | Required |
|---|---|---|---|
| Content-Type | String | Indicates the content type for the payload. Possible values are application/json or text/csv. |
Yes |
Request body
{
"annotations": [{
"uploadId": string,
"filePathInUpload": string,
"evaluationWeight": integer,
"expectedTranscription": string
}]
}
| Field | Type | Description | Required? |
|---|---|---|---|
| annotations | Array | Array of annotation objects.The length of the array cannot exceed 1000. | Each annotation object must contain at least annotations[i].expectedTranscription or annotations[i].uploadId plus annotations[i].filePathInUpload together. The annotations[i].uploadId plus annotations[i].filePathInUpload pair must always be present or absent together. |
| annotations[i].uploadId | String | Upload Id obtained when you create an upload with Catalog API. | Required when annotations[i].expectedTranscription is missing. When annotations[i].uploadId is present, annotations[i].filePathInUpload must also be present. |
| annotations[i].filePathInUpload | String | Path in the uploaded zip file. For example, consider a zip file containing a folder named 'folder' and with an audio file named audio.mp3 in that folder. The path is folder/audio.mp3. Use a forward slash ('/') to concatenate directories. | Required when annotations[i].expectedTranscription is missing. When annotations[i].filePathInUpload is present, annotations[i].uploadId must also be present. |
| annotations[i].expectedTranscription | String | Expected transcription text for the input audio. The acceptable length of the string is between 1 and 500 Unicode characters | Required when annotations[i].uploadId and annotations[i].filePathInUpload are missing. |
| annotations[i].evaluationWeight | Integer | Weight of the test case in an evaluation. Use this value for calculating metrics such as OVERALL_ERROR_RATE. Acceptable values are from 1 - 1000, from least to most significant. | Yes |
CSV content type
The order of the columns doesn't matter for CSV content because the first line of the CSV payload specifies the column ordering.
See the previous table for definitions of the attributes used in the CSV payload.
uploadId,filePathInUpload,evaluationWeight,expectedTranscription
string,string,integer,string
Response
HTTP status
HTTP 204 No Content
Response headers
None.
Response body
None.
Error response
The following table lists call-specific errors. For a reference of errors that can apply to all ASR APIs, see Automatic Speech Recognition (ASR) API Error Reference.
| HTTP Status Code | Error Code | Scenario |
|---|---|---|
| 400 Bad Request | MISSING_REQUIRED_PROPERTY | Required fields are missing from the request payload. |
| CONTENT_PARSE_FAILURE | Request payload is malformed< | |
| INVALID_INTEGER_VALUE | The provided annotations[i].weight is not within allowed range.
|
|
| INVALID_STRING_LENGTH | Length of provided annotations[i].expectedTranscription is not within allowed range.
|
|
| INVALID_ARRAY_SIZE | Length of annotations is not within allowed range. | |
| INVALID_CONTENT_TYPE | Value in Content-Type is not acceptable. | |
| INVALID_REQUEST_PARAMETER | Annotation set Id is malformed. | |
| RESOURCE_NOT_FOUND | Referenced annotations[i].uploadId cannot be found. |
|
Referenced annotations[i].filePathInUpload cannot be found in the annotations[i].uploadId. |
||
| 404 Not Found | RESOURCE_NOT_FOUND | Requested skill does not exist. |
| Requested annotation set does not exist. | ||
| 500 Internal Server Error | INTERNAL_SERVER_ERROR | Request failed due to an internal server error. |
Examples
| Sample Request | Sample Response |
|---|---|
PUT v1/skills/amzn.skill.id.1234/asrAnnotationSets/123456-1234123-123123/annotations HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"annotations":[
{
"uploadId": "1234-12314-12314",
"filePathInUpload":"hello_world.mp3",
"evaluationWeight":5,
"expectedTranscription":"alexa hello world"
},
{
"uploadId":"1234-12314-12315",
"filePathInUpload": "ask say hello.wav",
"evaluationWeight": 10,
"expectedTranscription": "ask hello world skill say hello"
},
{
"uploadId": "1234-12314-12348",
"filePathInUpload": "ask say hello.wav",
"evaluationWeight":10,
"expectedTranscription": "ask hello world skill say hello"
},
{
"uploadId": "1234-12314-12348",
"filePathInUpload":"something.wav",
"evaluationWeight": 10,
"expectedTranscription": "ask hello world skill say hello"
}
]
}
|
HTTP 204 No Content
|
PUT v1/skills/amzn.skill.id.1234/asrAnnotationSets/123456-1234123-123123/annotations HTTP/1.1
Content-Type: text/csv
Accept: application/json
filePathInUpload,uploadId,weight,expectedTranscription
hello_world.mp3,amazn.upId.12341234,5,alexa hello world
ask say hello.wav,amazn.upId.12341234,10,ask hello world skill say hello
ask say hello.wav,amazn.upId.12341234,10,ask hello world skill say hello
something.wav,amazn.upId.12341234,10,ask hello world skill say hello
|
HTTP 400 BadRequest
Content-Type: application/json
{
"message": "Payload validations failed."
"violations": [
{
"message": "File path \"hello.wav\" cannot be found in upload id \"amazn.upId.12341234\"",
"code", "RESOURCE_NOT_FOUND"
}
]
}
|
PUT v1/skills/amzn.skill.id.1234/asrAnnotationSets/123456-1234123-123123/annotations HTTP/1.1
Content-Type: text/csv
Accept: application/json
{}
|
HTTP 400 BadRequest
Content-Type: application/json
{
"message": "Payload validations failed."
"violations": [
{
"message": "Payload cannot be parsed as text/csv content type",
"code", "CONTENT_PARSE_FAILURE"
}
]
}
|
