AI API

After this page you can send a chat, embeddings, image or rerank request to Hanzo Cloud, and know which model id to put in it.

The AI API is where Hanzo Cloud runs inference. It sits on the same host as every other Hanzo service — api.hanzo.ai — behind the same hk-* key. An application that already calls Hanzo for storage or search does not pick up a second base URL or a second credential to start calling models.

Your first request

Mint a key, then:

curl https://api.hanzo.ai/v1/chat/completions \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zen5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Changing model is changing that one string. Nothing else about the request moves — not the host, not the key, not the body shape.

The models are ours

Two families are trained at Hanzo and served here first-party. Reach for them first:

• enso — our frontier family, for work that has to be right. Three tiers: enso-flash, enso, enso-ultra. What each is for →
• Zen — our open-weight models. Call them here, or download the weights and run them on your own hardware; the ids below are the hosted ones. zenlm.org →

zen-voice, zen-music, zen-video and zen-foley cover the remaining modalities. The full list, with context windows and current rates, is the Models page — and GET /v1/models is the source of truth for both.

Models from outside labs are carried too, and you reach them by naming their id on this same endpoint with this same key. That is a convenience for teams who need a specific outside model in one workflow. It is not what this product is.

Endpoints

All relative to https://api.hanzo.ai.

GET /v1/models needs a bearer token like every other endpoint. It returns each model's id, owned_by, premium flag and pricing.

Streaming

Set "stream": true and the response arrives as server-sent events, one chat.completion.chunk per data: line, with the text in choices[0].delta.content.

curl https://api.hanzo.ai/v1/chat/completions \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zen5",
    "messages": [{"role": "user", "content": "Count to three"}],
    "stream": true
  }'

Routing

Some ids are not one model but a choice we keep current. best resolves to whichever model we would pick for general work today, so you can ship against it and inherit upgrades without a deploy. Name a specific id instead whenever you need the answer to be reproducible.

Per-key budgets, rate limits and usage are set and read in the Console; see API keys.

Wire compatibility

/v1/chat/completions, /v1/embeddings and /v1/responses take and return the same JSON shapes as the widely-implemented chat-completions format. That shape is an interchange format we do not own and had no reason to re-invent, so an HTTP client written against it works here once its base URL points at https://api.hanzo.ai/v1 and it sends a Hanzo key.

Related

In this section