Get Annotation Set Automatic Speech Recognition (ASR) Contents API
Call this API to download the annotation set contents in text/csv or application/json format.
HTTP method and path
GET v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}/annotations?maxResults={maxResults}&nextToken={nextToken}
Attributes | Type | Description | Required |
---|---|---|---|
skillId | String | Skill Id as part of the URI path. | Yes |
annotationSetId | String | Annotation set Id as part of the request URI path. | Yes |
maxResults | Integer | Query parameter for indicating the maximum number of results to return. Default is 1000. The server might limit the number to fewer results than the specified maxResults value. | No |
nextToken | String | Query parameter for indicating continuation token. | No |
Note: The
maxResults
query parameter only applies if the value in Accept
header is application/json
. If the Accept
header value is text/csv
, the annotation set contents won't paginated even if you specify maxResults
as a query parameter. Returning unpaginated results simplifies importing the CSV data into spreadsheet applications.Request
Request headers
Accept: [text/csv, application/json]
Attributes | Type | Description | Required |
---|---|---|---|
Accept | String | Request header indicating what content type the client accepts as response. Possible values are text/csv – Returns annotation set contents in CSV format and application/json – Returns annotation set contents in JSON format. |
Yes |
Request body
None.
Response
HTTP status
HTTP 200 OK
Response headers
Content-Type: [text/csv, application/json]
Response body
Content-Type: application/json
{
"paginationContext": {
"nextToken": string
},
"annotations": [{
"uploadId": string,
"filePathInUpload": string,
"evaluationWeight": integer,
"expectedTranscription": string,
"audioAsset": {
"downloadUrl": string,
"expiryTime": string
}
}]
}
Attributes | Type | Description | Required |
---|---|---|---|
annotations[i] | Object | Annotation object. Valid values are uploadId , filePathInUpload , evaluationWeight , expectedTranscription , and audioAsset . |
Yes |
audioAsset | Object | Object containing information about downloading audio. Present when uploadId and filePathInUpload are available. |
No |
audioAsset.downloadUrl | String | Pre-signed download URL for downloading the audio file. | Required when audioAsset is present. |
audioAsset.expiryTime | String | Timestamp for the audio download URL expiration date in ISO 8601 format. | Required when audioAsset is present. |
paginationContext | Object | Object containing pagination information. If present, the response contains incomplete annotationSets. If omitted, all annotationSets were already returned. | No |
paginationContext.nextToken | String | Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of annotations. |
Content-Type: text/csv
uploadId,filePathInUpload,evaluationWeight,expectedTranscription,audioAssetDownloadUrl,audioAssetDownloadUrlExpiryTime
string,string,integer,string,string,string
Attributes | Type | Description | Required |
---|---|---|---|
uploadId | String | Upload Id returned when you create an upload using the Catalog API. | Must be present when expectedTranscription is missing. When uploadId is present, filePathInUpload must also be present. |
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. | Yes |
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 through 1000, from least to most significant. | Yes |
expectedTranscription | String | Expected transcription text for the input audio. The acceptable length of the string is between 1 and 500 Unicode characters. | Yes |
audioAssetDownloadUrl | String | URL for downloading the audio. | Yes |
audioAssetDownloadUrlExpiryTime | String | Timestamp for when the download URL expires in ISO - 8601 format. | Yes |
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 |
---|---|---|
404 Not Found |
RESOURCE_NOT_FOUND |
Requested skill cannot be found. |
Requested annotation set cannot be found. |
||
400 Bad Request |
INVALID_REQUEST_PARAMETER |
AnnotationSetId is malformed. |
Value of nextToken is invalid. |
||
INAVLID_INTEGER_VALUE | Value of maxResults query parameter is not within the allowed range. | |
MISSING_REQUIRED_PROPERTY |
Accept header is missing. |
|
INVALID_ENUM_VALUE |
The value in the Accept header is not accepted. |
|
PARAMETER_EXPIRED | nextToken is expired. | |
500 Internal Server Error |
INTERNAL_SERVER_ERROR |
Request failed due to an internal server error. |
Examples
Sample Request | Sample Response |
---|---|
GET /v1/skills/1234/asrAnnotationSets/1234-1234-12341234/annotations HTTP/1.1
Accept: text/csv
|
HTTP 200 OK
Content-Type: text/csv
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
|
GET /v1/skills/1234/asrAnnotationSets/1234-1234-12341234/annotations HTTP/1.1
Accept: application/json
|
HTTP 200 OK
Content-Type: application/json
{
"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-12 10:23:32AM"
}
},
{
"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-12 10:23:32AM"
}
},
{
"uploadId": "1234-12314-12348",
"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-12 10:23:32AM"
}
},
{
"uploadId": "1234-12314-12348",
"filePathInUpload":"something.wav",
"evaluationWeight":10,
"expectedTranscription":"ask hello world skill say hello",
"audioAsset": {
"downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf",
"expiryTime": "2019-10-12 10:23:32AM"
}
}
]
}
|
GET /v1/skills/1234/asrAnnotationSets/1234-1234-12341234/annotations?maxResults=1 HTTP/1.1
Accept: application/json
|
HTTP 200 OK
Content-Type: application/json
{
"paginationContext": {
"nextToken": "1234"
},
"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-12 10:23:32AM"
}
}
]
}
|
GET /v1/skills/1234/asrAnnotationSets/1234-1234-12341234/annotations?maxResults=1?nextToken=1234 HTTP/1.1
Accept: application/json
|
HTTP 200 OK
Content-Type: application/json
{
"paginationContext": {
"nextToken": "2345"
},
"annotations":[
{
"uploadId": "1234-12314-12315",
"filePathInUpload":"hello_alexa.mp3",
"evaluationWeight":5,
"expectedTranscription":"alexa hello world",
"audioAsset": {
"downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf",
"expiryTime": "2019-10-13 10:23:32AM"
}
}
]
}
|
GET /v1/skills/1234/asrAnnotationSets/1234-1234-12341234/annotations HTTP/1.1
Accept: application/json
|
HTTP 400 Bad Request
Content-Type: application/json
{
"message": "Annotation set not found",
"violations": [{
"message": "Annotation set identified by 1234-1234-12341234 cannot be found",
"code": "RESOURCE_NOT_FOUND"
}]
}
|
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
- Create annotation set API
- 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