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" } ] }