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