Create an Annotation Set API

The Create an Annotation Set API creates an empty annotation set for an Automatic Speech Recognition (ASR) Evaluation. Call Update Annotation Set Annotations to add audio file annotations to the set after creating the annotation set.

To learn more about the intended API flow for ASR Evaluation, see ASR implementation steps.

HTTP method and path

POST v1/skills/{skillId}/asrAnnotationSets
Field Type Description Required
skillId String Skill id as part of the URI path. Yes

Request

Request headers

 Content-Type: application/json
 Accept: application/json

Request body

{
    "name": string
}
Attributes Type Description Required
name String Name of the annotation set with a max length of 170 chars. Yes

Response

HTTP status

HTTP 200 OK

Response headers

Content-Type: application/json
Location: v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}
Attributes Type Description Required
skillId String Skill Id as part of the Location header URI. Yes
annotationSetId String Annotation set Id as part of the Location header URI. Yes

Response body

{
   "id": string
}
Attributes Type Description Required
id String Id of newly created annotation set. Use the format: 'amzn1.ask.asr-annotation-set.{UUID}'. For example, 'amzn1.ask.asr-annotation-set.524575b7-d845-4b61-a472-ce6e1fe4210a'. Yes

Error response

This section lists call-specific errors. For a reference of errors that can apply to all ASR APIs, see Automatic Speech Recognition API Error Reference.

HTTP Status Code Error Code Scenario

400 Bad Request

 MISSING_REQUIRED_PROPERTY Required fields are missing in the request payload.

CONTENT_PARSE_FAILURE

Malformed request payload.

INVALID_STRING_LENGTH

Length of the Name field is outside of the allowed range.

INVALID_REQUEST_PARAMETER

Name field contains invalid characters.

404 Not Found

RESOURCE_NOT_FOUND

Requested skill does not exist

500 Internal Server Error

INTERNAL_SERVER_ERROR

Request failed due to an internal server error

Examples

Sample Request Sample Response
POST /v1/skills/1234/asrAnnotationSets HTTP/1.1 Content-Type: application/json Accept: application/json { "name": "my annotation set name" } HTTP 200 OK Content-Type: application/json Location: /v1/skills/1234/asrAnnotationSets/amzn1.ask-asr-evaluation.asid.524575b7-d845-4b61-a472-ce6e1fe4210a { "id": "amzn1.ask.asr-evaluation.524575b7-d845-4b61-a472-ce6e1fe4210a" }
POST /v1/skills/1234/asrAnnotationSets HTTP/1.1 Content-Type: application/json Accept: application/json { "name": "" }
HTTP 400 Bad Request Content-Type: application/json { "message": "Payload validations failed", "violations": [{ "message": "The \"name\" property at property path \"$.name\" is outside the allowed range. Actual length: 0, Minimum length: 1", "code": "INVALID_STRING_LENGTH" }] }
POST /v1/skills/1234/asrAnnotationSets HTTP/1.1 Content-Type: application/json Accept: application/json {}
HTTP 400 Bad Request Content-Type: application/json { "message": "Payload validations failed", "violations": [{ "message": "Object at property path \"$\" has missing required property \"name\"" "code": "MISSING_REQUIRED_PROPERTY" }] }