Automatic Speech Recognition Annotation Set REST API Reference
Use the Automatic Speech Recognition (ASR) Annotation Set REST API to define annotation sets for your skill. An annotation set is a catalog of audio files used to evaluate speech recognition for your skill's interaction model. After you create an annotation set, you can run an ASR evaluation on the annotation set. For ASR Evaluation APIs, see Automatic Speech Recognition (ASR) Evaluation API Reference.
API endpoint
The endpoint of the ASR API is https://api.amazonalexa.com
.
Authentication
Each API request must have an authorization header whose value is a bearer token retrieved from Login with Amazon (LWA). For details, see Get an Access Token for SMAPI.
Operations
The ASR API includes the following operations.
Operation | HTTP method and URI |
---|---|
| |
| |
| |
| |
| |
| |
|
Create annotation set
Create a new annotation set. Fill the annotation set with pre-recorded sample audio utterances by calling Update annotations.
Request
To create an annotation set, you make a POST
request to the asrAnnotationSets
resource.
Request path and header example
POST /v1/skills/{skillId}/asrAnnotationSets
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill for which to create an annotation set. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
{
"name": "QuickTrivia annotation set1"
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Name for the annotation set. |
String |
Yes |
Response
A successful response returns HTTP 200 OK
with a Location
parameter in the request header. The response body contains the annotation set ID. Use the ID to reference and add sample utterances to the annotation set.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"id": "annotation.set.1"
}
Response body properties
Property | Description | Type | Required |
---|---|---|---|
|
Identifies the new annotation set. |
String |
Yes |
HTTP status codes
Status | Description |
---|---|
|
Empty annotation set created successfully. The response header contains a
|
|
Server can't process the request due to a client error. For example, the payload is malformed, the annotation set is malformed or empty.
|
|
Authorization token is invalid, expired, or doesn't have access to the resource. |
|
The requested operation isn't allowed. |
|
The requested resource isn't found. For example, the
|
|
Request to run an evaluation for a given skill conflicts with an evaluation request that's currently in progress. |
|
User has exceeded the permitted rate limit. |
|
Server has encountered an error. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Delete annotation set
Delete the specified annotation set.
Request
To delete an annotation set, you make a DELETE
request to the asrAnnotationSets
resource.
Request path and header example
DELETE /v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill. |
String |
Yes |
|
Path |
Identifies the annotation set to delete. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 204 No Content
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Annotation set deleted successfully. |
|
Server can't process the request due to a client error. For example, the payload is malformed, the annotation set is malformed or empty.
|
|
Authorization token is invalid, expired, or doesn't have access to the resource. |
|
The requested operation isn't allowed. |
|
The requested resource isn't found. For example, the
|
|
Request to run an evaluation for a given skill conflicts with an evaluation request that's currently in progress. |
|
User has exceeded the permitted rate limit. |
|
Server has encountered an error. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get annotation set contents
Download the contents of the specified annotation set in comma-separated values (CSV) or JSON format.
Request
To download the contents of the annotation set, you make a GET
request to the asrAnnotationSets
resource.
Request path and header example
GET /v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}/annotations?maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: {accept-type}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill. |
String |
Yes |
|
Path |
Identifies the annotation set. |
String |
Yes |
|
Query |
Maximum number of items to return. |
Number |
No |
|
Query |
Token that you use to get the next set of annotations, after you receive a response with truncated results. Set this parameter to the value of |
String |
No |
|
Header |
String |
Yes | |
|
Header |
Specifies the requested format of the returned contents. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with the contents of the annotation set in the specified format.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
CSV response body example
When you specify CSV format, the response body includes the entire contents. The first row of the response body contains comma-delimited attribute names of the annotation properties. Subsequent rows define the annotations. The annotation properties in each row follow the strict ordering of the attribute property names defined in the first row.
The following example shows a response in CSV format.
filePathInUpload,uploadId,evaluationWeight,expectedTranscription,audioAssetDownloadUrl,audioAssetDownloadUrlExpiryTime
hello_world.mp3,amazn.catalog.upid.12341234,5,alexa hello world, https://audio.s3.amazon.com/XXXYYYA, 2020-04-013 13:23PM TZ
ask say hello.wav,amazn.catalog.upid.12341234,10,ask hello world skill say hello, https://audio.s3.amazon.com/XXXYYYA,2020-04-013 13:23PM TZ
ask say hello.wav,amazn.catalog.upid.12341234,10,ask hello world skill say hello, https://audio.s3.amazon.com/XXXYYYA, 2020-04-013 13:23PM TZ
something.wav,amazn.catalog.upid.12341234,10,ask hello world skill say hello, https://audio.s3.amazon.com/XXXYYYA, 2020-04-013 13:23PM TZ
CSV response body properties
The order of the columns doesn't matter because the first line of the CSV payload specifies the column ordering.
Property | Description | Type |
---|---|---|
|
Path to the audio file in the uploaded zip file.
For example, for a zip file that contains a folder, named |
String |
|
Identifies the uploaded audio content. The Catalog API returns the identifier each time you create an upload. |
String |
|
Weight of the test case in an evaluation. Used to calculate metrics, such as overall error rate. |
Integer |
|
Expected transcription text for the input audio. |
String |
|
Identifies the presigned URL at which to download the audio. |
String |
|
Expiration date for the download URL. |
String |
JSON response body example
The following example shows a response in JSON format.
{
"annotations": [{
"uploadId": "1234-12314-12314",
"filePathInUpload": "hello_world.mp3",
"evaluationWeight": 5,
"expectedTranscription": "alexa hello world",
"audioAsset": {
"downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf",
"expiryTime": "2019-10-12T10:20:50.52Z"
}
},
{
"uploadId": "1234-12314-12315",
"filePathInUpload": "ask say hello.wav",
"evaluationWeight": 10,
"expectedTranscription": "ask hello world skill say hello",
"audioAsset": {
"downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf",
"expiryTime": "2019-10-12T10:20:50.52Z"
}
}
]
}
JSON response body properties
Property | Description | Type |
---|---|---|
|
Sample utterances that are part of the annotation set. |
Array of objects |
|
Path to the audio file in the uploaded zip file. |
String |
|
Identifies the uploaded audio content. The Catalog API returns the identifier each time you create an upload.
|
String |
|
Weight of the test case in an evaluation. Used to calculate metrics, such as overall error rate. |
Integer |
|
Expected transcription text for the input audio. |
String |
|
Specifies how to download the audio file. |
Object |
|
Identifies the presigned URL at which to download the audio file. |
String |
|
Expiration date for the download URL. |
String |
|
Indicates there is more content. If present, the response contains a subset of the annotations. When there is no more content, |
Object |
|
Identifies the next set of annotations to return. The token expires in 24 hours. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the contents of the annotation set. |
|
Server can't process the request due to a client error. For example, the payload is malformed, the annotation set is malformed or empty.
|
|
Authorization token is invalid, expired, or doesn't have access to the resource. |
|
The requested operation isn't allowed. |
|
The requested resource isn't found. For example, the
|
|
Request to run an evaluation for a given skill conflicts with an evaluation request that's currently in progress. |
|
User has exceeded the permitted rate limit. |
|
Server has encountered an error. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get annotation set metadata
Get the metadata for the specified annotation set.
Request
To get the metadata for an annotation set, you make a GET
request to the asrAnnotationSets
resource.
Request path and header example
GET /v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill. |
String |
Yes |
|
Path |
Identifies the annotation set. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with the annotation set metadata.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"name": "QuickTrivia annotation set1",
"annotationCount": 12,
"lastUpdatedTimestamp": "2019-08-12T18:46:31.674Z"
}
Response body properties
Property | Description | Type |
---|---|---|
|
Name of the annotation set. |
String |
|
Number of annotations in the annotation set. |
Integer |
|
Timestamp of the last update to the annotation set. |
String |
|
(Optional) Indicates whether an evaluation can be run against the annotation set. If set to |
Boolean |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the metadata for the annotation set. |
|
Server can't process the request due to a client error. For example, the payload is malformed, the annotation set is malformed or empty.
|
|
Authorization token is invalid, expired, or doesn't have access to the resource. |
|
The requested operation isn't allowed. |
|
The requested resource isn't found. For example, the
|
|
Request to run an evaluation for a given skill conflicts with an evaluation request that's currently in progress. |
|
User has exceeded the permitted rate limit. |
|
Server has encountered an error. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
List annotation sets
Get all annotation sets for the specified skill.
Request
To list all annotation sets for the specified skill, you make a GET
request to the asrAnnotationSets
resource.
Request path and header example
GET /v1/skills/{skillId}/asrAnnotationSets?nextToken={nextToken}&maxResults={maxResults}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill. |
String |
Yes |
|
Query |
Maximum number of items to return. |
Number |
No |
|
Query |
Token that you use to get more items in the list, after you receive a response with truncated results. Set this parameter to the value of |
String |
No |
|
Header |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with a list of annotation sets.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"annotationSets": [{
"id": "annotation.set.1",
"name": "my annotation set",
"annotationCount": 10,
"lastUpdatedTimestamp": "2019-08-12T18:46:31.674Z"
},
{
"id": "amzannotation.set.2",
"name": "my annotation set 2",
"annotationCount": 5,
"lastUpdatedTimestamp": "2019-08-12T18:46:31.674Z"
},
{
"id": "annotation.set.3",
"name": "my annotation set 3",
"annotationCount": 5,
"lastUpdatedTimestamp": "2019-08-12T18:46:31.674Z"
}
]
}
Response body properties
Property | Description | Type |
---|---|---|
|
List of annotation sets. |
Array of objects |
|
Identifies the annotation set. |
String |
|
Name of the annotation set. |
String |
|
Number of annotations in the annotation set. |
Integer |
|
Timestamp of the last update to the annotation set. |
String |
|
(Optional) Indicates whether an evaluation can be run against the annotation set. If set to |
Boolean |
|
Indicates there are more matching results. If present, the response contains a subset of the results. When there are no more matching results, |
Object |
|
Identifies the next set of annotations to return. The token expires in 24 hours. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains a list of annotation sets. |
|
Server can't process the request due to a client error. For example, the payload is malformed, the annotation set is malformed or empty.
|
|
Authorization token is invalid, expired, or doesn't have access to the resource. |
|
The requested operation isn't allowed. |
|
The requested resource isn't found. For example, the
|
|
Request to run an evaluation for a given skill conflicts with an evaluation request that's currently in progress. |
|
User has exceeded the permitted rate limit. |
|
Server has encountered an error. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update annotations
Add or update annotations in an existing annotation set.
Before you add or update annotations, make sure that you create a catalog and an annotation set. For more details about the API call sequence, see ASR implementation steps.
Request
To update the annotation set, you make a PUT
request to the asrAnnotationSets
resource.
Request path and header example
PUT /v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}/annotations
Host: api.amazonalexa.com
Content-Type: {content-type}
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill. |
String |
Yes |
|
Path |
Identifies the annotation set. |
String |
Yes |
|
Header |
Specifies the format of the included updates. |
String |
Yes |
|
Header |
String |
Yes |
CSV request body example
When you specify CSV format, the request body includes the entire contents. The first row of the request body must contain comma-delimited attribute names of the annotation properties. Subsequent rows define the annotations. The annotation properties in each row must follow the strict ordering of the attribute property names defined in the first row.
The following example shows a request in CSV format.
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
CSV request body properties
The order of the columns doesn't matter because the first line of the CSV payload specifies the column ordering.
Property | Description | Type | Required |
---|---|---|---|
|
Path to the audio file in the uploaded zip file. |
String |
Yes |
|
Identifies the uploaded audio content. The Catalog API returns the identifier each time you create an upload. |
String |
Yes |
|
Weight of the test case in an evaluation. Used to calculate metrics, such as overall error rate. |
Integer |
Yes |
|
Expected transcription text for the input audio. |
String |
Yes |
JSON request body example
The following example shows a request in JSON format.
{
"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"
}
]
}
JSON request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Sample utterances that are part of the annotation set. |
Array of objects |
Yes |
|
Path to the audio file in the uploaded zip file. |
String |
Yes |
|
Identifies the uploaded audio content. The Catalog API returns the identifier each time you create an upload. |
String |
Yes |
|
Weight of the test case in an evaluation. Used to calculate metrics, such as overall error rate. |
Integer |
Yes |
|
Expected transcription text for the input audio. |
String |
Yes |
Response
A successful response returns HTTP 204 No Content
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Annotation set updated successfully. |
|
Server can't process the request due to a client error. For example, the payload is malformed, the annotation set is malformed or empty.
|
|
Authorization token is invalid, expired, or doesn't have access to the resource. |
|
The requested operation isn't allowed. |
|
The requested resource isn't found. For example, the
|
|
Request to run an evaluation for a given skill conflicts with an evaluation request that's currently in progress. |
|
User has exceeded the permitted rate limit. |
|
Server has encountered an error. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update metadata
Update the metadata for for the specified annotation set.
Request
To update the annotation set, you make a PUT
request to the asrAnnotationSets
resource.
Request path and header example
PUT /v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill. |
String |
Yes |
|
Path |
Identifies the annotation set. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
{
"name": "QuickTrivia annotation set10"
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Name of the annotation set. |
String |
Yes |
Response
A successful response returns HTTP 204 No Content
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Annotation set properties updated successfully. |
|
Server can't process the request due to a client error. For example, the payload is malformed, the annotation set is malformed or empty.
|
|
Authorization token is invalid, expired, or doesn't have access to the resource. |
|
The requested operation isn't allowed. |
|
The requested resource isn't found. For example, the
|
|
Request to run an evaluation for a given skill conflicts with an evaluation request that's currently in progress. |
|
User has exceeded the permitted rate limit. |
|
Server has encountered an error. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |