How to Use HefuAI with the OpenAI Python SDK

Maggie fu — Tue, 27 Oct 2026 07:20:35 +0000

The Problem

You want to try Kimi, DeepSeek, Claude, GPT. Each provider means a new account, a new API key, a new billing setup, and sometimes a whole new SDK. By the time you've evaluated three vendors, you've spent an afternoon on signup forms instead of your actual project.

HefuAI is an API gateway that puts 130+ models behind one OpenAI-compatible endpoint. What actually sold me: I didn't have to learn anything new. If you've called the OpenAI API before, you already know how to call this one. Two lines change.

Everything below goes from an empty file to a working streaming chat call.

Prerequisites

Python 3.9+
A free HefuAI account (sign up at hefu.hk — new accounts get $0.5 bonus credit for API usage)
An API key from Console → API Keys

⚠️ One heads-up: HefuAI keys are stored irreversibly and the plaintext is shown only once at creation. Copy it somewhere safe immediately. I learned this the hard way.

Step 1: Install the SDK

pip install openai python-dotenv

That's the official OpenAI SDK. No special client needed.

Step 2: Store Your API Key

Create a .env file in your project root (and add it to .gitignore before your first commit):

HEFUAI_API_KEY=sk-your-key-here

# quickstart.py
import os
from dotenv import load_dotenv

load_dotenv()

Never hardcode the key in source files. A leaked key means someone else's API bill.

Step 3: Point the Client at HefuAI

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HEFUAI_API_KEY"],
    base_url="https://api.hefu.hk/v1",
)

Only api_key and base_url differ from a standard OpenAI setup. Request shapes, response objects, error types: all the same.

Step 4: Make Your First Request

resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "user", "content": "Explain what an API gateway is in one sentence."}
    ],
)

print(resp.choices[0].message.content)
print(resp.usage)

Example output (yours will vary)

An API gateway is a single entry point that receives requests, routes them to the
appropriate backend service, and handles cross-cutting concerns like auth and rate
limiting.
Usage(prompt_tokens=..., completion_tokens=..., total_tokens=...)

Your text and token counts change between runs. The structure doesn't: the answer is in resp.choices[0].message.content, the token counts in resp.usage.

Want another model? Swap "deepseek-v4-flash" for "kimi-k3" or "claude-sonnet-5-5" and run it again. Same code, same key.

Step 5: Add Streaming (Do This Early)

Add streaming early. Reasoning models can sit for tens of seconds before they return anything, and a spinner that long reads as broken. With streaming, the first token arrives in seconds, at least for reasoning models that stream their thinking.

stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Write a haiku about API keys."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if delta and delta.content:
        print(delta.content, end="", flush=True)
print()

Want real token counts at the end of a stream? Pass stream_options={"include_usage": True}. A usage chunk arrives after the last content chunk.

Common Mistakes

The /v1 in the base URL. https://api.hefu.hk on its own doesn't route. It has to be https://api.hefu.hk/v1.
Keys that end up in git. Use .env with python-dotenv, and fix .gitignore before the first commit, not after.
Trailing whitespace in the key. Copying out of a dashboard drags a newline along more often than you'd expect. It's the usual reason behind a 401.
No max_tokens cap. Chatty models will run long and the bill follows. Set a cap per scenario.
Model ID typos. A wrong ID gives you a 404 and nothing else. Check the console's model list before you start debugging your own code.

Beyond Chat Completions

The same key also covers:

/v1/messages — the Anthropic Messages protocol, if you prefer the anthropic SDK
/v1/responses — the Responses API for codex-style coding models

Existing OpenAI-SDK code runs as-is once base_url and api_key change, and LangChain-style stacks pick it up without extra wiring.

Docs: hefu.hk/docs · Model list: hefu.hk/models

Next Steps

Next post takes this further: calling several models through one API from a single script, which is what you need for evaluation and A/B testing before you commit to one model in production.

Disclosure: this tutorial series uses HefuAI as its example gateway. All code patterns apply to any OpenAI-compatible endpoint.

DEV Community: Maggie fu