Step by Step Guide for using 2Hz Krisp API

Recently we launched Krisp API, which is the first of its kind AI powered Speech Enhancement API. We are thrilled about this.

Though the API is quite simple to use for web developers (REST API with async interface), we thought that we should provide even a simpler mechanism so that you can test the API in few steps.

This blog post will provide a step by step guide for playing with the API.

Async API

In its current incarnation Krisp API works with files only. It receives files, processes and sends them back. Since the files can be large we have decided to design the API as asynchronous. This means that you need to provide a webhook so that we send the result back to you.

Webhook is a simple HTTP(S) server built by you. When your client sends a request to Krisp API it specifies webhook URL. After API completes the task – it makes an HTTP POST request back to the webhook and provides the response.

This is a well known pattern used by various large APIs (e.g. Twilio).

Here is a diagram of how it works:

Client is the piece of software that will make request to Krisp API. It may be a simple curl command, python script, nodejs script or anything that is capable of doing HTTP request. 

The simplest way of playing with the API

For those of you who just want to test Krips API without building your webhook server, I’ve developed a small nodejs module that allows to use Krisp API from a local machine.

All you need is Node JS and npm running on your local machine. You can install both using this tutorial.

Here is the link to krisp-api-ngrok. Simply follow the instructions in Readme and you will be able to test Krisp API under 5 minutes.

This module runs ngrok from inside and opens a webhook on your local machine.

This is it. If you want to build your own server – keep reading.

Build your own Webhook Server

Let’s setup a basic node js webhook server. First of all you need to install nodejs on your local machine. Here is an awesome tutorial explaining how to do that.

Make a folder on your home directory and name it krisp-api-tutorial. And setup a node project using npm.

mkdir ~/krisp-api-tutorial && cd ~/krisp-api-tutorial
npm init

Follow the instructions then create a javascript file called server.js

nano server.js

And paste the following code into that file

const express = require('express')
const app = express()
const port = 3000

app.get('/', (req, res) => {
   console.log(req.body);
   res.send(`OK`)
})

app.listen(port, () => console.log(`Example app listening on port ${port}!`))

Now run that file using node

node server.js

Congratulations, now you’ve set up your webhook server that logs response from Krisp API.

Now I’ll assume that you have received an AccountRID and AccountKey for 2Hz API. Let’s use curl to interact with Krisp API and provide our webhook url and param for identifying this request. We need the webhook server to be up and running so do not stop it.

curl --request POST \
 --url https://api.2hz.ai/v2/se/denoise/file/ \
 --header 'Authorization: Basic {{account_rid}}:{{account_key}}' \
 --header 'content-type: multipart/form-data' \
 --form file=@{{PATH/TO/YOUR/FILE.wav}} \
 --form modelName=DENOISE_PLAY_16000 \
 --form webhook=https://{{YOUR_WEBHOOK_ADDRESS}} \
 --form param=THIS_IS_REQUEST_FROM_TUTORIAL

Here you will need to replace the account_rid, account_key, webhook, file.

After executing this command Krisp API will process your file using noise suppression model DENOISE_PLAY_16000 and will make POST request to webhook server with the urls of original and noise suppressed versions of the file.

Author: Melik Karapetyan is a Machine Learning Engineer at 2Hz.

Leave a Reply

Your email address will not be published.