Skip to main content

Get Started with our Quickstart Tutorial

Introducing an API solution tailored for Africa’s most widely spoken languages. This vulavula API offers transcription and sophisticated analysis capabilities, enabling seamless comprehension and integration. Are you ready to dive in? Let's go!

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

Get your API Token​

In order to get access to our API, you’re going to need an API token. Signup and login to the Vulavula Platform HERE. Generate a API token. This’ll be used to authenticate your requests.

Transcribe​

Transcribe your audio files to text. This is the first step to unlocking the power of your audio data.

Setup​

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

# 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 = "https://vulavula-services.lelapa.ai/api/v1/transport/file-upload"

# The transcribe API URL to kick off your transcription job.
TRANSCRIBE_URL = "https://vulavula-services.lelapa.ai/api/v1/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 the 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,
)

Response:

{
  "upload_id": "240a180d-553f-456f-912e-14cdc628869c",
  "customer_id": 5,
  "project_id": 5
}

Let's 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"
- South African 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()

Response:

{ "message": "Message sent to process queue." }

Analyse

Analyse your text to extract insights.

# 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://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()

Response:

{
  "Id": "33abd8be-4a0c-4db8-947e-077ad5a88d8b",
  "Sentiments": [
    {
      "text": "Ngijabulile",
      "sentiment": [
        {
          "label": "positive",
          "score": 0.9990226030349731
        }
      ]
    }
  ]
}

Translate

Translate your text from one language to another. You can also translate to other languages by changing the source_lang and target_lang parameter:

  • Northern Sotho (nso_Latn)
  • Afrikaans (afr_Latn)
  • Southern Sotho (sot_Latn)
  • Swati (ssw_Latn)
  • Tsonga (tso_Latn)
  • Tswana (tsn_Latn)
  • Xhosa (xho_Latn)
  • Zulu (zul_Latn)
  • English (eng_Latn)
  • Swahili (swh_Latn)
# Because our model sometimes go to sleep, we have implemented a retry to try again.
from retry_requests import retry
from requests import Session

TRANSLATION_URL = "https://vulavula-services.lelapa.ai/api/v1/translate/process"

headers={
    "X-CLIENT-TOKEN": VULAVULA_TOKEN,
}

# Get retry helper session
session = retry(Session(), retries=10, backoff_factor=1)

payload = {
  "input_text": "Lo musho ubhalwe ngesiZulu.",
  "source_lang": "zul_Latn",
  "target_lang": "eng_Latn"
}

translation_resp = session.post(
    TRANSLATION_URL,
    json=payload,
    headers=headers,
)

translation_resp.json()

Response:

{
  "id": "deed7995-dcf4-4456-bd33-c92ca1d990ca",
  "translation": [
    {
      "translation_text": "This sentence is written in Zulu."
    }
  ]
}

Support​

Struggling to get started? Check out our Colab Tutorial or Contact us and we’ll help you sort it out.