Python SDK

The Vulavula Python SDK wraps the Vulavula API in a Python library, so you can transcribe and translate without writing HTTP calls by hand.

Getting started

Prerequisites

• Python 3.7 or newer — download it from python.org if needed
• A Vulavula API key — see Authentication

1. Set up a virtual environment (optional)

You can install the vulavula library into a virtual environment to keep it isolated from other projects. Skip this step if you don't want one.

Code
# Create virtual environment
python -m venv vulavula-env

# Activate the virtual environment

# On Windows
vulavula-env\Scripts\activate

# On macOS and UNIX
source vulavula-env/bin/activate

2. Install the SDK

You can use either pip or pdm:

Code
pip install vulavula

3. Initialize the client

Pass your API key when constructing the client:

Code
from vulavula import VulavulaClient

client = VulavulaClient("<INSERT_TOKEN>")

4. Make your first request

Translate a sentence from isiZulu to English:

Code
translation_result = client.translate({
    "input_text": "Lo musho ubhalwe ngesiZulu.",
    "source_lang": "zul_Latn",
    "target_lang": "eng_Latn",
})
print("Translation Result:", translation_result)

Error handling

The SDK raises VulavulaError, a custom exception with detailed information about API failures. Standard HTTP response codes indicate the outcome of a request:

• 2xx — success
• 4xx — a problem with the input (e.g. a missing required parameter)
• 5xx — an error on Vulavula's servers

Handle errors with a try/except block:

Code
from vulavula.common.error_handler import VulavulaError

try:
    translation_result = client.translate({
        "input_text": "Lo musho ubhalwe ngesiZulu.",
        "source_lang": "zul_Latn",
        "target_lang": "eng_Latn",
    })
    print("Translation Result:", translation_result)
except VulavulaError as e:
    print("An error occurred:", e.message)
    if 'details' in e.error_data:
        print("Error Details:", e.error_data['details'])
    else:
        print("No additional error details are available.")
except Exception as ex:
    print("An unexpected error occurred:", str(ex))

Next steps

• Transcribe audio with the SDK's webhook-based flow — see the Speech-to-Text SDK guide
• Compare with the raw HTTP endpoints in the API Reference
• See the Vulavula project page on PyPI for the full package description and configuration options