API Reference

The Attendi Speech Service API allows you to quickly obtain an accurate transcription of an uploaded audio file. The API is a SaaS solution for healthcare institutions. We have different language models dedicated to a variety of domains within healthcare. This document will take you through the basic steps to get the Attendi Speech Service API up and running, so that you can integrate it seamlessly into your own application. We will show you how to authenticate your requests to the API, link customers and transcribe audio.

API Keys

The Attendi Speech Service API uses your account’s API keys to authenticate requests. Attendi will provide you with your API keys. If you don’t include your API key when making an API request, the Speech Service API returns an error.

There are two types of API keys: publishable and secret.

  • Publishable keys are used to identify your tenant to the API and are not secret. This means that you can use the publishable key in your JavaScript frontend, or in a mobile application.
  • Secret keys should be kept confidential, and you should only store them on your servers. You must not share your secret API key with any third parties. The secret API key should be treated like a password.
Key Prefix Authorization
Public pk_ Transcribe audio directly from a client application where the API key cannot be secured
Secret sk_ Use the Customers endpoints. Transcribe audio via machine-to-machine communication

Authentication

Authentication to the API is done via a custom HTTP header. Provide your API key in the following header: x-API-key.

All API requests must be made over HTTPS. Requests made over HTTP will fail, so will API requests made without authentication.

Cross-Origin requests are only allowed for the transcribe endpoint, using your public key from a frontend application.

Security

We implemented and rely on end-to-end TLS/SSL encryption. This allows us to encrypt and securely transmit data to the backend and send the transcribed result to your app. We only accept requests over HTTPS.

Quickstart guide 

Linking customers

Requests to transcribe audio with the Attendi Speech Service API can be parameterized with a customer ID, allowing you to keep track of the usage of each specific customer. There are several customer endpoints that allow you to create, update or retrieve customers. Each customer has both an internal ID (generated by us) and an external ID (provided by you). The name of a customer can be updated using the internal or the external ID. In case you want to update the customer name using the internal ID we provided you with, you need to use the PATCH method. If you want to use the external ID to insert or update the customer’s name, you should use the PUT method.

Transcribing audio

You can send a POST request to the /v1/speech/transcribe endpoint to obtain a transcription of an audio file. The audio file you want to transcribe must be encoded in base64 so that the binary audio data is converted into characters. Additionally, the audio should meet the following specifications:

  • Single (mono) channel recording
  • 16 kHz sampling rate
  • 16-bit audio recording

In case your file does not meet these requirements, you can use a tool to convert it. ffmpeg is a command line tool, which you can use to convert your audio as follows:

ffmpeg -i {input_file.wav} -acodec pcm_s16le -ac 1 -ar 16000 {output_file.wav}

Environments

Environment Use URL
SANDBOX Test the API on a test enviroment https://sandbox.api.attendi.nl
PRODUCTION Run the API on a production environment https://api.attendi.nl

Example code

API docs

Transcribe

1
curl -I --request POST 'https://sandbox.api.attendi.nl/v1/speech/transcribe' --header 'Content-Type: application/json' --header 'x-API-key: sk_<key_here>' --data-raw '{ "audio": ""}'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
    byte[] data = // audio bytes
    var requestBody = new TranscribeRequest(data);
    var client = new HttpClient();
    client.DefaultRequestHeaders.Add("x-API-key", "sk_<key_here>");
    var response = await client.PostAsJsonAsync("https://sandbox.api.attendi.nl/v1/speech/transcribe", requestBody);
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

public class TranscribeRequest
{
    public TranscribeRequest(byte[] audio)
    {
        Audio = audio;
    }
    public byte[] Audio { get; private set; }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
import base64
import requests

audio_file = # Path to audio file to transcribe
API_KEY = # Provided API key

with open(audio_file, "rb") as f:
  audio = f.read()

base64_audio = base64.b64encode(audio).decode("utf-8")

response = requests.post(
  "https://sandbox.api.attendi.nl/v1/speech/transcribe",
  headers={"x-api-key": 'sk_<key_here>'},
  json={"audio": base64_audio})

print(response.json())

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import { ITranscript } from "./models/ITranscript";
import { API } from "./APIUtils";

const convertBlobToBase64 = (blob: Blob) =>
  new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onerror = reject;
    reader.onload = () => {
      const base64String = reader.result?.toString();
      if (base64String) {
        resolve(base64String.substr(base64String.indexOf(",") + 1));
      } else {
        resolve(reader.result);
      }
    };
    reader.readAsDataURL(blob);
  });

export async function transcribeAudio(blob: Blob) {
  const blobBase64 = await convertBlobToBase64(blob);

  const body = {
    audio: blobBase64,
  };

  return API.post<ITranscript>("/v1/speech/transcribe", body);
}

Customers

CREATE CUSTOMER

1
curl --request POST 'https://sandbox.api.attendi.nl/v1/customers' --header 'Content-Type: application/json' --header 'x-API-key: sk_<key_here>' --data-raw '{ "name": "MyTestCustomer", "externalId": "1AB2"}'

LIST CUSTOMERS

1
curl --request GET 'https://sandbox.api.attendi.nl/v1/customers' --header 'x-API-key: sk_<key_here>'

CREATE CUSTOMER

1
2
3
4
5
6
7
8
public async Task CreateCustomer(string customerName, string externalId)
        {
             var request = new CreateCustomerRequest(customerName, externalId);
            client.DefaultRequestHeaders.Add("x-API-key", "sk_<key_here>");
             var response = await _client.PostAsJsonAsync("https://sandbox.api.attendi.nl/v1/customers", request);
            var responseBody = await response.Content.ReadAsStringAsync();
            Console.WriteLine(responseBody);
        }

LIST CUSTOMERS

1
2
3
4
5
6
7
public async Task GetCustomers()
        {
            client.DefaultRequestHeaders.Add("x-API-key", "sk_<key_here>");
             var response = await _client.GetAsync("https://sandbox.api.attendi.nl/v1/customers");
            var responseBody = await response.Content.ReadAsStringAsync();
            Console.WriteLine(responseBody);
        }

CREATE CUSTOMER

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import requests

url = "https://sandbox.api.attendi.nl/v1/customers"

payload = {'name': 'MyCustomer', 'externalId': '1AB2'}
headers = {'Content-Type': 'application/json', 'x-API-key': 'sk_<key_here>'}
response = requests.request("POST", url, headers=headers, json=payload)

print(response) # Will print <Response [201] if successful
print(response.text)

LIST CUSTOMERS

1
2
3
4
5
6
7
8
import requests

url = "https://sandbox.api.attendi.nl/v1/customers"

headers = {'x-API-key': 'sk_<key_here>'}

response = requests.request("GET", url, headers=headers)
print(response.text)

ERVAAR ZELF DE MOGELIJKHEDEN

Ben je benieuwd naar de mogelijkheden van Attendi? Neem dan vooral contact met ons op voor een demo of een persoonlijk gesprek.