Hanzo Python SDK
hanzoai is the Python client for the Hanzo API, generated from the API's own
OpenAPI document. Every /v1 route is in it, and the names it exposes are the
document's operation ids. .spec-lock names the commit and sha256
of the document this tree was cut from.
Install
pip install hanzoai
Check the install without a key — GET /v1/models is public:
python -m examples.models
https://api.hanzo.ai serves 112 models, no credential required
all-mini-lm-l6-v2 · do-ai · $0.02/Mtok in
anthropic-claude-opus-5 · do-ai · $1/Mtok in
…
Quickstart
import os
from hanzoai.cloud import ApiClient, Configuration, KeysApi
client = ApiClient(Configuration(
host="https://api.hanzo.ai",
access_token=os.environ["HANZO_API_KEY"],
))
with client as api:
for key in KeysApi(api).get_keys().keys or []:
print(key.prefix, key.type, key.created_at)
Every route follows that shape: one *Api class per tag, one method per
operation, typed models in and out.
Auth
access_token is the whole configuration — it becomes
Authorization: Bearer <token> on every operation that asks for a credential.
Four operations do not: GET /v1/models, GET /v1/models/providers,
GET /v1/commands, GET /v1/openapi.json. They send no credential, which is why
examples/models runs before you have a key.
Keys come from cloud.hanzo.ai or hanzo login in two
shapes, and only one of them works here. Use an sk-: it carries a principal,
which every credentialled call needs. A pk- is publishable — safe in a browser
bundle because it names an org and authenticates nobody — so cloud refuses it at
the identity boundary.
No generated code reads the environment, so no variable you export reaches a
request on its own. (The hand-written hanzoai.zap and hanzoai.config read
HANZO_ZAP_ENDPOINT and HANZO_CONFIG_HOME; neither is a credential.)
examples/client.py is where HANZO_API_KEY and
HANZO_BASE_URL get resolved, for all six flows.
Examples
examples/ carries one directory per flow. Each is a whole path through one part
of the API. CI imports all six and resolves every method name they call against
the client.
| flow | what it does | routes | key |
|---|---|---|---|
models |
the model catalog | GET /v1/models |
none |
hello |
prove the key works | GET /v1/keys |
sk- |
money |
balance + usage | GET /v1/billing/balance, GET /v1/billing/usage |
sk- |
store |
KV round-trip | POST /v1/kv, GET/DELETE /v1/kv/{name} |
sk- |
agent |
create, run, read the runs | POST /v1/agents, POST /v1/agents/{ref}/run, GET /v1/agents/{ref}/runs |
sk- |
tools |
the tool catalog | GET /v1/tools |
sk- |
One command each, from the repo root:
python -m examples.models # no credential
export HANZO_API_KEY=sk-...
python -m examples.hello
A real key prints your keys; a bogus one prints
HTTP 403: {"code":"forbidden","error":"sign in to manage API keys"}.
There is no chat flow: POST /v1/chat/completions is declared with no
requestBody and no responses, so the method takes no arguments and returns
None. It comes back the day the document describes the body.
money reads its two payloads through the generated
*_without_preload_content variant, for the same reason — an operation that
declares no responses, or a 2xx carrying no content, models no body to
deserialize.
Reference for the routes themselves: api.hanzo.ai/docs, served from the same document — api.hanzo.ai/v1/openapi.json.
The rest of the repo
This is a uv workspace. pkg/hanzoai is the client above; the other packages
are hand-written, ship separately, and mostly carry their own README:
| Package | Install | Purpose |
|---|---|---|
pkg/hanzoai |
hanzoai |
the client above |
pkg/hanzo-mcp |
hanzo-mcp |
Model Context Protocol server |
pkg/hanzo-agent |
hanzo-agent |
agent framework (import path agents) |
pkg/hanzo-agents |
hanzo-agents |
agent networks and swarms |
pkg/hanzo-memory |
hanzo-memory |
persistent memory + RAG over SQLite |
pkg/hanzo-network |
hanzo-network |
distributed compute nodes |
pkg/hanzo-tools-* |
one each | single-concern tool packages, each registering a TOOLS list under the hanzo.tools entry point, which is how hanzo-mcp finds them |
The hanzo command is a native binary, not a Python package:
curl -fsSL https://hanzo.sh | sh. pip install hanzo ships the older Python CLI
under the name hanzo-py, so the two never fight over one name on a PATH.
Development
git clone https://github.com/hanzoai/python-sdk && cd python-sdk
uv sync --all-packages
uv run pytest tests/ -v
pkg/hanzoai/cloud/ is generated and is never edited by hand — a regeneration
does rmtree then copytree, so an edit there is gone on the next run. It comes
from hanzoai/openapi:
cd ../openapi && uv run --with pyyaml python3 generate.py python \
--repo ../python-sdk --spec ../cloud/openapi.yaml
A defect in generated code is fixed in the document.
License
Apache 2.0 — see LICENSE. Report vulnerabilities to security@hanzo.ai (SECURITY.md).
Hanzo — the Open AI Cloud
hanzo.ai · docs.hanzo.ai · same client in other languages: TypeScript · Go · Java · Kotlin · umbrella
Release files for hanzoai 8.5.156
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| hanzoai-8.5.156.tar.gz | 2.1 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hanzoai-8.5.156-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 7.2 MB
Release files / hanzoai-8.5.156.tar.gz
| Download URL | hanzoai-8.5.156.tar.gz |
|---|---|
| Size | 2.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4d4d8e9cf9033c74b47385566822d05bcdcf391f32da71a7b7cde3825fda8071
|
|
BLAKE2b-256 checksum How to use checksums |
e943ac0eb586a91e1206352529c3c3eb6ff45d2e26cebafaab890d545398eb7e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / hanzoai-8.5.156-py3-none-any.whl
| Download URL | hanzoai-8.5.156-py3-none-any.whl |
|---|---|
| Size | 5.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
622d64647d0637d1a5994defe16a33bf70bdc3e122ce7d25f0a4f388e12d47c5
|
|
BLAKE2b-256 checksum How to use checksums |
4b9abc5acd92096204affdc4477c777a35bcf3a12070fbe2d668972d63298984
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
