VULAVULA BETA DOCUMENTATION

Introducing an API solution tailored for Africa’s most widely spoken languages. This Beta API offers transcription and sophisticated analysis capabilities, enabling seamless comprehension and integration, for Sesotho, Afrikaans, South African English and isiZulu. Are you ready to dive in?

We have swagger docs deployed HERE for further information on how to engage with the key.

Get your API token

In order to get access to our API, you’re going to need an API token.

Signup and login to Vulavula Beta HERE
Generate a Beta API token. This’ll be used in the X-CLIENT-TOKEN header in your requests
There is a limit of 100 free calls per token.

We recommend you checkout our Colab Tutorial to easily interact with the APIs

NOTE: Our models sometimes go to sleep (because running all day is tiring and expensive). 
We're busy streamlining our morning routine and optimizing our energy. 

Until we get that right, you might occasionally receive a 503 HTTP error when using our APIs. 

We ask you to retry the call until the model has woken up.

TRANSCRIPTION

Let’s get transcribing in isiZulu, seSotho, Afrikaans and South African English!

DATASHEETS
Lelapa-Datasheet-Lelapa-X-ASR-isiZulu-and-seSotho.pdf

Lelapa-Datasheet-Lelapa-X-ASR-ZA-English.pdf

Lelapa-Datasheet-Lelapa-X-ASR-Afrikaans.pdf

MODEL CARDS
Lelapa-Model-Card-Lelapa-X-ASR-isiZulu-and-seSotho.pdf

Lelapa-Model-Card-Lelapa-X-ASR-ZA-English.pdf

Lelapa-Model-Card-Lelapa-X-ASR-Afrikaans.pdf

SETUP AND CONFIG

Install pip install retry-requests.This allows us to retry requests.

# Because our model sometimes go to sleep, we have implemented a retry to try again.
from retry_requests import retry
from requests import Session

VULAVULA_BASE_URL = “https://beta-vulavula-services.lelapa.ai/api/v1/”
 
# Get your VULAVULA_TOKEN by logging in and getting keys
VULAVULA_TOKEN = “<INSERT TOKEN HERE>”
 
# Our headers for authentication
headers={“X-CLIENT-TOKEN”: VULAVULA_TOKEN,}
 
# The transport API to upload your file
TRANSPORT_URL = urljoin(VULAVULA_BASE_URL,“transport/file-upload”)
 
# The transcribe API URL to kick off your transcription job.
TRANSCRIBE_URL = urljoin(VULAVULA_BASE_URL,“transcribe/process/”)
 
# When transcription is complete, our system calls a webhook that you provide.
# Here, we’re using a demo webhook from webhook.site for testing.
WEBHOOK_URL=“https://webhook.site/3594b17d-a879-41b8-bb28-e59d08e16be6”
 
# Name of the file you are transcribing
FILE_TO_TRANSCRIBE = “<FILE TO TRANSCRIBE>”

UPLOAD YOUR SOUND FILE

Right now it’s single files only, and is a little fiddly. Check it out in coming weeks and we’ll have a slightly different API

# Get file size
file_size = os.path.getsize(FILE_TO_TRANSCRIBE)
# Open file in binary mode
with open(FILE_TO_TRANSCRIBE, ‘rb’) as file:
# Read file
file_content = file.read()
# Encode file content
encoded_content = base64.b64encode(file_content)
# Decode bytes to string
encoded_string = encoded_content.decode()
transport_request_body = {
“file_name”: FILE_TO_TRANSCRIBE,
“audio_blob”: encoded_string,
“file_size”: file_size,
}
resp = requests.post(
TRANSPORT_URL,
json=transport_request_body,
headers=headers,
)
print(f“Upload status {resp.status_code}“)
print(f“Upload response {resp.json()}“)

LETS GET TRANSCRIBING

Our responses to the API are delivered by webhook, which you configure in this call below.

Additionally, optionally, you can specify a language code to specify which model you’re speaking on. The following language codes are valid

AFRIKAANS = “afr”
ISIZULU = “zul”
SESOTHO = “sot”
RSA_ENGLISH = “eng”

If no language code is specified, our built-in language ID will select the most probably language.

upload_id = resp.json()[“upload_id”]
TRANSCRIBE_URL = f“{TRANSCRIBE_URL}{upload_id}“
process = requests.post(TRANSCRIBE_URL, json={“webhook”:WEBHOOK_URL,“language_code”:“zul”}, headers=headers,)
process.json()

NAMED ENTITY RECOGNITION

Our named entity recognition is a simply post request. We include a retry in case our models are still sleeping

DATASHEET
Lelapa-Datasheet-Lelapa-X-NER-isiZulu.pdf

MODEL CARD
Lelapa-Model-Card-Lelapa-X-NER-isiZulu.pdf

# Because our model sometimes go to sleep, we have implemented a retry to try again.
from retry_requests import retry
from requests import Session
NER_URL = “https://beta-vulavula-services.lelapa.ai/api/v1/entity_recognition/process”
sentence = “President Ramaphosa gaan loop by Emfuleni Municipality”
headers={“X-CLIENT-TOKEN”: VULAVULA_TOKEN}
 
# Get retry helper session
session = retry(Session(), retries=10, backoff_factor=1)
ner = session.post(
NER_URL,
json={“encoded_text”: sentence},
headers=headers,)
ner.json()

SENTIMENT AnALYSIS

Sentiment analysis is a simple call to our servers.

DATASHEET
Lelapa-Datasheet-Lelapa-X-Sentiment-isiZulu.pdf

MODEL CARD
Lelapa-Model-Card-Lelapa-X-Sentiment-isiZulu.pdf

# Because our model sometimes go to sleep, we have implemented a retry to try again.
from retry_requests import retry
from requests import Session
SENTIMENT_URL = “https://beta-vulavula-services.lelapa.ai/api/v1/sentiment_analysis/process”
sentence = “Ngijabulile!” # I am happy
headers={“X-CLIENT-TOKEN”: VULAVULA_TOKEN,}

# Get retry helper session
session = retry(Session(), retries=10, backoff_factor=1)
sentiment_resp = session.post(
SENTIMENT_URL,
json={“encoded_text”: sentence},
headers=headers,
)
sentiment_resp.json()