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 using the ASR Evaluation tool.
Make sure that you have created a catalog for your upload before uploading your files. See API Flow to learn about the API call sequence for creating a catalog, creating an annotation set, and populating that annotation set for ASR evaluations.
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. | Yes |
| annotations[i].uploadId | String | Upload Id obtained when you create an upload with Catalog API. | Yes |
| annotations[i].filePathInUpload | String | File 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 file path is folder/audio.mp3. Use a forward slash ('/') to concatenate directories. | Yes |
| annotations[i].expectedTranscription | Expected transcription text for the input audio. The acceptable length of the string is between 1 and 500 Unicode characters | String | Yes |
| annotations[i].evaluationWeight | 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. | Integer | Yes |
CSV content type
The order of the columns doesn't matter for CSV content; the first line of the CSV payload specifies the column ordering.
Please 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
This section 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 annotations[i].weight is not within allowed range. |
|
|
INVALID_STRING_LENGTH |
Length of 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"
}
]
}
|
