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.
Customers
You can create customers that will be part of your account. Each customer will get an API key, so that you can authenticate your request, and identify your customer to us at the same time.
There are two types of API keys: customer and secret.
Customer keys are used to identify your tenant and the specific customer the transcribe request is for. It is not a 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
Customer
ck_
Idenitifies your customer and allows you to 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 customer 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
Customers
There are several customer endpoints that allow you to create, update or retrieve customers. You need to create a customer with the id you use in your internal systems. There is a PUT method that will allow you to upsert a customer. This way, it easy to syncronize changes from your internal systems to ours, just send the complete object everytime. We also have a PATCH endpoint if you only want to update a specific field. You can retrieve a specific customer by your ID, or get all customers.
Customer API Key
Each customer will have it’s own API key. This key starts with **ck_**. You can reroll the API key by using the reroll endpoint.
Model Type
When creating or updating a customer, you need to provide a default model value for the customer. This model determines what Speech to Text model we will use if you do not provide an override value in the transcribe request. This model type can be updated with the PUT and PATCH endpoints.
Linking customers
NOTE: Only for secret API keys. This behaviour is included automatically with customer keys.
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.
Units
Units are the representation in our system for a location or a team of a customer. Sometimes, customers want to roll out per location. In order to make it easy to measure the adoption rate and activity per location/team, we need to know the teams and locations.
The endpoints for units are very similar to customer. As a unit is created within a customer, the URI always starts with /v1/customers/{customerId}/units. Then you can use PUT to upsert a unit again, using your own ID to create the unit in the Attendi system. There is also a PATCH endpoint to update a existing unit, using your ID. For each customer, you can retrieve a specific unit by ID, or retrieve all units for a specific customer.
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:
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.