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

Related topics

• What is Automatic Speech Recognition?
• Create an Annotation Set for Automatic Speech Recognition (ASR)
• Run an Automatic Speech Recognition (ASR) Evaluation
• Improve your Automatic Speech Recognition (ASR) Test Results
• Update annotation set annotations API
• Post ASR evaluation API
• Get ASR evaluation results API
• Create catalog API
• Batch Test Your Natural Language Understanding (NLU) Model