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