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}

Besides the audio file, it is required to select the specific language model you want to use (DistrictCare, ResidentialCare or MentalHealthcare). You also have to add a unique UserID. The unique UserID could be anything, for example a UUID. We do not save any personal data, only the unique UserID. We use this UserID to measure usage, and to ensure that we can easily trace back any problems with the functionality. Furthermore, there is an option to add the browser’s User-Agent as metadata.

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

Sample Apps

Transcribe

1

curl --request POST 'https://sandbox.api.attendi.nl/v1/speech/transcribe' --header 'Content-Type: application/json' --header 'x-API-key: sk_<key_here>' --data-raw '{"userId": "user_id_here", "config": {"model": "<add_model_here>"}, "metadata": {"userAgent": "string"}, "audio": "base64_encoded_audio_here"}'

 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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


{
    byte[] audioData = { } // audio bytes
    var config = new TranscribeConfig("ResidentialCare");
    var metadata = new TranscribeMetadata(".NET Console App");
    var request = new TranscribeRequest(audioData, "127121df-e3e5-4d74-a8d7-cf48c45e6460", config, metadata);
    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", request);
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

public class TranscribeRequest
{
    public TranscribeRequest(byte[] audio, string userId, TranscribeConfig transcribeConfig, TranscribeMetadata metadata = null)
    {
        Audio = audio;
        UserId = userId;
        Config = transcribeConfig;
        Metadata = metadata;
    }

    [Required]
    public byte[] Audio { get; private set; }
    [Required]
    public string UserId { get; private set; }
    [Required]
    public TranscribeConfig Config { get; private set; }
    public TranscribeMetadata Metadata { get; private set; }
}

public class TranscribeConfig
{
    [Required]
    public string Model { get; private set; }

    public TranscribeConfig(string model)
    {
        Model = model;
    }
}

public class TranscribeMetadata
{
    public string UserAgent { get; private set; }

    public TranscribeMetadata(string userAgent)
    {
        UserAgent = userAgent;
    }
}

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


import base64
import requests

audio_file = # Path to audio file to transcribe

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={"userId": "<user_id_here", "config": {"model": "<add_model_here"}, "metadata": {"userAgent": "string"}, "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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


// SpeechAPI.ts
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,
  userId: string,
  modelType: string
) {
  const blobBase64 = await convertBlobToBase64(blob);

  const body = {
    audio: blobBase64,
    userId: userId,
    config: {
      model: modelType,
    },
    metadata: {
      userAgent: navigator.userAgent, // only works in browser
    },
  };

  return API.post<ITranscript>("/v1/speech/transcribe", body);
}
// ITranscript.ts
export interface ITranscript {
  transcript: string;
}

// APIUtils.ts
import axios from "axios";

export const API = axios.create({
  baseURL: process.env.REACT_APP_BASE_API_URL,
  headers: {
    "Content-Type": "application/json",
    "x-API-key": process.env.REACT_APP_API_KEY,
  },
});

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.

Contact