Pronunciation Challenges

A text transcription with reference audio allow a detailed, phoneme level analysis on user submitted audio.

List all pronunciation challenges

URL

GET /challenges/pronunciation HTTP/1.1

Request

GET /challenges/pronunciation HTTP/1.1
Accept: application/json

Response

The response is a JSON list with pronunciation challenges.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "pronunciation_1",
    "created": "2014-01-28T21:25:10Z",
    "updated": "2014-01-28T21:25:10Z",
    "transcription": "You could take the baby with you",
    "referenceAudioUrl": "https://api.itslanguage.io/download/YsjdG37bUGseu8-bsJ",
    "status": "preparing",
    "language": "eng",
    "alignment": null
  },
  {
    "id": "12",
    "created": "2014-01-28T21:25:10Z",
    "updated": "2014-01-28T21:25:10Z",
    "transcription": "tap",
    "referenceAudioUrl": "https://api.itslanguage.io/download/YsjdG37bUGseu6-Abq",
    "status": "prepared",
    "language": "eng",
    "alignment": {
      "confidenceScore": -3.44,
      "words": [
        {
          "chunks": [
            {
              "graphemes": "t",
              "phonemes": [
                {
                  "start": 0.25,
                  "end": 0.45,
                  "confidenceScore": -2.8149,
                  "ipa": "t"
                }
              ]
            },
            {
              "graphemes": "a",
              "phonemes": [
                {
                  "start": 0.45,
                  "end": 0.67,
                  "confidenceScore": -0.7412,
                  "ipa": "ae"
                }
              ]
            },
            {
              "graphemes": "p",
              "phonemes": [
                {
                  "start": 0.67,
                  "end": 0.84,
                  "confidenceScore": -6.7516,
                  "ipa": "p"
                }
              ]
            }
          ]
        }
      ]
    }
  }
]

Get a single pronunciation challenge

URL

GET /challenges/pronunciation/:challenge HTTP/1.1
  • challenge - Required The pronunciation challenge identifier.

Request

GET /challenges/pronunciation/pronunciaton_1 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "12",
  "created": "2014-01-28T21:25:10Z",
  "updated": "2014-01-28T21:25:10Z",
  "transcription": "tap",
  "referenceAudioUrl": "https://api.itslanguage.io/download/YsjdG37bUGseu6-Abq",
  "status": "prepared",
  "language": "eng",
  "alignment": {
    "confidenceScore": -3.44,
    "words": [
      {
        "chunks": [
          {
            "phonemes": [
              {
                "start": 0.25,
                "ipa": "t",
                "end": 0.45,
                "confidenceScore": -2.8149
              }
            ],
            "graphemes": "t"
          },
          {
            "phonemes": [
              {
                "start": 0.45,
                "ipa": "ae",
                "end": 0.67,
                "confidenceScore": -0.7412
              }
            ],
            "graphemes": "a"
          },
          {
            "phonemes": [
              {
                "start": 0.67,
                "ipa": "p",
                "end": 0.84,
                "confidenceScore": -6.7516
              }
            ],
            "graphemes": "p"
          }
        ]
      }
    ]
  }
}

Create a pronunciation challenge

URL

POST /challenges/pronunciation HTTP/1.1

Request parameters

Name Type Description
id string Optional The pronunciation challenge identifier. If none is given, one is generated.
transcription string Required The spoken word or sentence as plain text.
referenceAudio blob Required The reference audio fragment.
language string Required The language of the challenge in ISO 639-2 format

Request

POST /challenges/pronunciation HTTP/1.1
Accept: application/json
Content-Type: multipart/form-data; boundary=jhgd87g7Gy3d78

--jhgd87g7Gy3d78
Content-Disposition: form-data; name="referenceAudio"; filename="blob"
Content-Type: audio/ogg

<blob>
--jhgd87g7Gy3d78
Content-Disposition: form-data; name="transcription"

You could take the baby with you
--jhgd87g7Gy3d78--

Response

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://api.itslanguage.io/challenges/pronunciation/4

{
  "id": "4",
  "created": "2014-01-28T21:25:10Z",
  "updated": "2014-01-28T21:25:10Z",
  "transcription": "You could take the baby with you",
  "referenceAudioUrl": "https://api.itslanguage.io/download/YsjdG37bUGseu8-bsJ",
  "status": "preparing",
  "language": "eng",
  "alignment": null
}

Update a pronunciation challenge

URL

PUT /challenges/pronunciation/:challenge HTTP/1.1
  • challenge - Required The pronunciation challenge identifier.

Update one or more properties of an existing pronunciation challenge.

Request parameters

Name Type Description
transcription string Optional The spoken word or sentence in plain text.
referenceAudio blob Optional The reference audio fragment.
status string Optional The status of the challenge (unprepared, preparing, prepared).
language string Optional The language of the challenge in ISO 639-2 format
alignment object Optional The alignment of the challenge.

Request

PUT /challenges/pronunciation/4 HTTP/1.1
Accept: application/json
Content-Type: multipart/form-data; boundary=jhgd87g7Gy3d78

--jhgd87g7Gy3d78
Content-Disposition: form-data; name="transcription"

tap
--jhgd87g7Gy3d78
Content-Disposition: form-data; name="referenceAudio"; filename="blob"
Content-Type: audio/ogg

<blob>
Content-Disposition: form-data; name="status"

prepared
--jhgd87g7Gy3d78
Content-Disposition: form-data; name="aignment"
Content-Type: application/json

{"confidenceScore": -3.44, "words": [....]}
--jhgd87g7Gy3d78--

Response

HTTP/1.1 200 OK
Content-Type: application/json
Location: https://api.itslanguage.io/challenges/pronunciation/4

{
  "id": "4",
  "created": "2014-01-28T21:25:10Z",
  "updated": "2014-01-28T21:25:10Z",
  "transcription": "You could take the baby with you",
  "referenceAudioUrl": "https://api.itslanguage.io/download/YsjdG37bUGseu8-Abc",
  "status": "prepared",
  "language": "eng",
  "alignment": {"confidenceScore": -3.44, "words": [....]}
}

Delete a single pronunciation challenge

URL

DELETE /challenges/pronunciation/:challenge HTTP/1.1
  • challenge - Required The choice challenge identifier.

Request

DELETE /challenges/pronunciation/choice_1 HTTP/1.1

Response

HTTP/1.1 204 No Content