# Python

URL: https://docs.hanzo.ai/docs/sdks/python

> hanzoai on PyPI, Python 3.12 or newer, is the whole /v1 surface as hanzoai.cloud, and what the separate hanzo, hanzo-agents and hanzo-mcp distributions are for.

```bash
pip install "hanzoai>=8"
```

Python 3.12 or newer. The `>=8` is load-bearing: without it, pip on 3.9 to 3.11
resolves `hanzoai` to the 2.1 line, which has no `hanzoai.cloud`, and says
nothing. With it, pip refuses rather than install a different client.

That is the client for **every** `/v1` capability, generated from the API's own
document. It exposes exactly one thing:

```python
import hanzoai
hanzoai.cloud          # the client. Nothing else is re-exported at the top level.
```

> **Why nothing is flat**
>
> The distribution used to re-export \~2,200 names at `hanzoai.api` and
> `hanzoai.models`, from a document that had stopped existing — most of them built
> a request the server answered with a 404. They were removed rather than
> refreshed: two ways to call one API is already a defect, and the namespace
> already says which service and which document a symbol came from. Import from
> `hanzoai.cloud`.

Set the key once:

```bash
export HANZO_API_KEY="sk-..."   # from platform.hanzo.ai
```

## The shape

One `Configuration`, one `ApiClient`, and one class per product:

```python
import os
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AiApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))

models = AiApi(client).get_models()
```

The class is the product and the method is the operation, so the
[reference](https://docs.hanzo.ai/docs/openapi) is the index — each operation page prints this call
beside the raw HTTP.

## Chat completions

Use the `openai` client, pointed at Hanzo:

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HANZO_API_KEY"],
    base_url="https://api.hanzo.ai/v1",
)

answer = client.chat.completions.create(
    model="zen6",
    messages=[{"role": "user", "content": "Explain quantum computing"}],
)
print(answer.choices[0].message.content)
```

This is the recommendation rather than a workaround, and it is worth saying why.
`api.hanzo.ai/v1` speaks the OpenAI and Anthropic wire formats on purpose, so
streaming, tool calls and every helper that library already carries keep
working — the edit is the base URL and the key, which is all [Migrate from
OpenAI](https://docs.hanzo.ai/docs/guides/migrate/openai) asks for. Meanwhile `hanzoai` is generated
from the document, and the document states the chat route's address without
stating its body schema: `AiApi.post_chat_completions()` therefore takes no
request body and decodes no response. A generated client cannot invent a shape
nobody wrote down. Reach for `hanzoai` for the rest of `/v1`, which the OpenAI
client does not describe at all.

## The other distributions

The `hanzo` command is the native [CLI](https://docs.hanzo.ai/docs/cli), installed with
`curl -fsSL https://hanzo.sh | sh`, not a Python package. `hanzo` on PyPI is the
older Python CLI, installed as `hanzo-py` so the two never share a name on a
PATH. The agent and tool packages are their own
distributions, and `pip install "hanzo[all]"` is the convenience that pulls
them:

| Distribution   | What it is                                                             |
| -------------- | ---------------------------------------------------------------------- |
| `hanzo`        | The older Python CLI, as the `hanzo-py` command.                       |
| `hanzo-agents` | Client for the agents control plane.                                   |
| `hanzo-mcp`    | The [MCP](https://docs.hanzo.ai/docs/mcp) server, as a Python process. |
| `hanzo-memory` | The memory service.                                                    |
| `hanzo-aci`    | The agent–computer interface.                                          |

## Resources

- [`hanzoai` on PyPI](https://pypi.org/project/hanzoai/) ·
  [`hanzo` on PyPI](https://pypi.org/project/hanzo/)
- Source — [hanzoai/python-sdk](https://github.com/hanzoai/python-sdk) ·
  [hanzo-py](https://github.com/hanzo-py)
- [Every `/v1` operation →](https://docs.hanzo.ai/docs/openapi)