Skip to main content

Using Speechly Batch API

In this guide you'll learn how to use Speechly Batch API for transcribing pre-recorded audio files asynchronously.

Overview​

Using the Speechly Batch API is a three step process:

  1. Request an API token
  2. Send files for transcription
  3. Check the operation result

Requesting an API token​

Request an API token by calling the Identity API Login method using your Speechly Project ID.

curl \
  --request POST \
  --header 'Content-Type: application/json'  \
  --data '{"device_id": "'`uuidgen`'", "project": {"project_id":"YOUR_SPEECHLY_PROJECT_ID"}}' \
  --url 'https://api.speechly.com/speechly.identity.v2.IdentityAPI/Login'

Example response:

{
 "token": "YOUR-API-TOKEN",
 "valid_for_s": 86399,
 "expires_at_epoch": "1685175113",
 "expires_at": "2023-05-27T08:11:53.158784+00:00"
}

You can store the token value in a shell variable for quick access later on. This is optional, but it's used in this guide.

API_TOKEN=YOUR-API-TOKEN

Sending files for transcription​

Now that you have an API token, queue a URL to the audio file for processing by calling the ProcessAudioSource method.

curl \
  --request POST \
  --header 'Content-Type: application/json'  \
  --header 'Authorization: Bearer '$API_TOKEN  \
  --data '{"source": [{"source_url": "https://docs.speechly.com/audio/ndgt.wav"}]}' \
  --url 'https://api.speechly.com/speechly.slu.v2.BatchAPI/ProcessAudioSource'
Tip

Transcribe multiple files by appending a {"source_url":"URL"} object to the source array.

Example response:

{
  "operation": [
    {
      "id": "d3a95fe2-7a72-421a-a669-fcb40c5ecc3f",
      "reference": "",
      "batch_id": "",
      "batch_reference": "",
      "status": "STATUS_PENDING",
      "language_code": "",
      "app_id": "",
      "result": [],
      "error_code": "ERROR_UNSPECIFIED",
      "error_description": "",
      "source_url": "https://docs.speechly.com/audio/ndgt.wav",
      "destination_url": ""
    },
    // If you passed multiple sources, they will appear here
  ]
}

Copy the id value, you'll be needing it shortly.

Checking the operation results​

Finally, check the operation results by calling the QueryStatus method using the id from the previous response.

curl \
  --request POST \
  --header 'Content-Type: application/json'  \
  --header 'Authorization: Bearer '$API_TOKEN \
  --data '{"operation_ids": ["d3a95fe2-7a72-421a-a669-fcb40c5ecc3f"]}' \
  --url 'https://api.speechly.com/speechly.slu.v2.BatchAPI/QueryStatus'
Tip

Check multiple operation results by appending their ids to the operation_ids array.

Example response:

{
  "operation": [
    {
      "id": "d3a95fe2-7a72-421a-a669-fcb40c5ecc3f",
      "reference": "",
      "batch_id": "",
      "batch_reference": "",
      "status": "STATUS_DONE",
      "language_code": "en",
      "app_id": "66676952-1a35-4712-97db-30be0aefe971",
      "result": [
        {
          "type": "RESULT_TYPE_TRANSCRIPT_DISPLAY",
          "text": "Hi, I'm Neil deGrasse Tyson, astrophysicist. In addition to probing the secrets...",
          "tokens": []
        }
      ],
      "error_code": "ERROR_UNSPECIFIED",
      "error_description": "",
      "source_url": "https://docs.speechly.com/audio/ndgt.wav",
      "destination_url": ""
    },
    // If you passed multiple IDs, they will appear here
  ]
}
Info

The status of the operation is indicated by the status key. See Operation.Status reference for all statuses.

API reference​

Speechly Batch API V2