makimoto-kawa

Official Python SDK for Kawa's transcription API. makimoto is the shared namespace this SDK lives under, kawa is the specific product it talks to, more Makimoto products may get their own subpackage here later.

This is the maintained, typed client, with pydantic response models, structured exceptions, and a tested, versioned release process, built on top of the same API as the reference client in the main kawa repo. For the interactive playground, full API docs, and the OpenAPI spec, see the main kawa repo. Prefer a zero-dependency, copy-paste client instead of a pip package? See kawa_client.py there.

Install

Requires Python 3.10+.

pip install makimoto-kawa

Authentication

Get a token from the Makimoto dashboard: https://www.makimoto.ai/login.

For now, this is a short-lived JWT, not a persistent API key, it expires, so copy a fresh one from the dashboard if requests start failing with 401. This will change to a static API key in the near future; when it does, the same token/MAKIMOTO_API_TOKEN mechanism below will keep working, only what you paste in changes.

client = kawa.KawaClient(token="<dashboard-token>")

or set it once as an environment variable and omit the argument entirely:

export MAKIMOTO_API_TOKEN="<dashboard-token>"

An explicit token argument always wins over the environment variable if both are set.

Usage

from makimoto import kawa

client = kawa.KawaClient(token="<dashboard-token>")   # or set MAKIMOTO_API_TOKEN instead

job = client.transcribe("call.mp3", language="en")

if job.status == "succeeded":
    print(job.result.full_text)
else:
    print(job.error)

See examples/quickstart.py for a complete, runnable script, it ships with a small sample audio file, so python examples/quickstart.py works out of the box once MAKIMOTO_API_TOKEN is set.

transcribe() submits the recording and polls until it's done in one call, raising TimeoutError if it never finishes. For manual control, e.g. streaming live status updates to a UI, the lower-level primitives are still there:

job = client.create_transcription("call.mp3", language="en")

for update in client.poll(job.job_id):
    print(update.status)

Check your account's transcription quota:

usage = client.usage()
print(f"{usage.used_minutes}/{usage.limit_minutes} minutes used")

Release the client's connections when you're done with it, or use it as a context manager:

with kawa.KawaClient(token="<dashboard-token>") as client:
    ...

Errors

Every call raises kawa.KawaError on an API-level failure (bad status code, or a response that doesn't match the expected shape), and kawa.TimeoutError-compatible TimeoutError from transcribe() if a job never finishes in time. A failed transcription job (status == "failed") is not an exception, it's a normal result, check .status/.error as shown above.

try:
    job = client.transcribe("call.mp3")
except kawa.KawaError as exc:
    print(exc.status_code, exc.body)

Logging

Quiet by default. To see what the SDK is doing (credential source, a poll that gave up), or the raw HTTP traffic underneath it:

import logging
logging.basicConfig()  # attaches a handler so the lines below actually print somewhere
logging.getLogger("makimoto.kawa.client").setLevel(logging.DEBUG)  # this SDK's own events
logging.getLogger("httpx2").setLevel(logging.DEBUG)                 # every request/response

Development

See CONTRIBUTING.md.

Licence

MIT