API documentation

OpenAI-compatible interface to 16 large language models from 5 upstream providers.

5-minute quickstart

Get from zero to a successful API call in five minutes. No SDK install required.

1. Create an account

Go to api.houjiayan.com/register. You'll need an email address; we send a verification link. New accounts receive a ¥6.6 (approx. $1.00) sign-up bonus — no fixed expiry; it stays valid as long as your account is active.

2. Generate an API key

In the dashboard, click "Add a new token". Give it a name (e.g. "dev-laptop") and copy the key — it's shown only once.

3. Make your first call

Run the curl below. You should see a JSON response with a 'Hello!' message in the assistant role.

curl https://api.houjiayan.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

Prefer not to pick a model yourself? See Smart routing — set "model": "auto" and let the gateway choose.

Client setup recipes

Copy-paste configuration for popular OpenAI-compatible clients. Only the Base URL field differs per client — the exact value is noted for each.

Python (openai SDK)

base_url takes the full URL including /v1.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.houjiayan.com/v1"   # ← include /v1
)

Node.js (openai SDK)

baseURL takes the full URL including /v1.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.houjiayan.com/v1"   // ← include /v1
});

LangChain (ChatOpenAI)

Pass base_url with the full URL including /v1 (older LangChain versions use the openai_api_base parameter).

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="kimi-k2.6",
    api_key="YOUR_API_KEY",
    base_url="https://api.houjiayan.com/v1"   # older LangChain: openai_api_base=...
)

print(llm.invoke("Hello").content)

Cherry Studio

Add an OpenAI-compatible provider. The API host field takes the full URL including /v1.

Provider type : OpenAI (OpenAI-compatible)
API host    : https://api.houjiayan.com/v1   ← include /v1
API key     : sk-hjy-...
Models      : add by ID — e.g. kimi-k2.6, deepseek-v4-flash

NextChat / ChatGPT-Next-Web

The custom endpoint (BASE_URL) takes the bare domain WITHOUT /v1 — NextChat appends /v1/chat/completions itself. Entering .../v1 here double-prefixes the path and requests fail.

Custom endpoint (BASE_URL) : https://api.houjiayan.com   ← bare domain, NO /v1
API key                  : sk-hjy-...
Custom models            : +kimi-k2.6,+deepseek-v4-flash

OpenClaw

baseUrl takes the full URL including /v1 — OpenClaw does not append it. A domain-only value hits the gateway's web console and returns HTTP 200 with an HTML page instead of JSON; if you see that symptom, check this field first.

baseUrl : https://api.houjiayan.com/v1   ← include /v1 (not auto-appended)
apiKey  : sk-hjy-...
model   : kimi-k2.6   (or any ID from the models table)

cURL

No base URL field — call the full endpoint paths directly.

curl https://api.houjiayan.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

Code examples

cURL

curl https://api.houjiayan.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

Python (openai SDK)

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.houjiayan.com/v1"
)

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)

Node.js (openai SDK)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.houjiayan.com/v1"
});

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [{ role: "user", content: "Hello" }]
});
console.log(response.choices[0].message.content);

Streaming response (SSE)

Set stream: true to receive tokens as they are generated. Each chunk is a server-sent event with a delta field.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.houjiayan.com/v1"
)

stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Write a haiku about APIs"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Function calling

Most models support OpenAI-compatible tool calling. Define your tools in the tools array; the model returns structured tool_calls that you execute and feed back as tool role messages.

from openai import OpenAI
import json

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.houjiayan.com/v1")

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather in a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name"}
            },
            "required": ["city"]
        }
    }
}]

response = client.chat.completions.create(
    model="MiniMax-M2.7",
    messages=[{"role": "user", "content": "What's the weather in Hohhot?"}],
    tools=tools
)
tool_call = response.choices[0].message.tool_calls[0]
print(f"Call: {tool_call.function.name}({tool_call.function.arguments})")

Error codes

• 401 Invalid or missing API key. Check the Authorization header and that the key has not been revoked.
• 402 Insufficient balance. Top up via the dashboard, or request a refund if the 24h window applies.
• 403 API key does not have access to this model, or account is suspended for Terms violation.
• 404 Model name is unknown. Use /v1/models to list all available models.
• 413 Request payload too large. Reduce prompt size or use a model with larger context window.
• 429 Rate limit hit. The gateway auto-retries on a different upstream where possible. If persistent, see Rate limits below.
• 500/502/503/504 Upstream provider error. The gateway returns the error from the source. Try a different model, or retry with exponential backoff.
• 529 All upstream providers are overloaded. The gateway could not complete the request. Retry after 30 seconds.

Rate limits

Per-user limits: 60 requests/minute, 100K tokens/minute (input + output combined). The gateway auto-failover ensures that if one upstream returns 429, traffic shifts to another provider where available. If you need higher limits, email support@houjiayan.com with your use case.

Concurrent requests

Up to 5 concurrent in-flight requests per API key. Exceeding this returns 429. For batch workloads, use the /v1/batch endpoint (coming Q4 2026).

Best practices

• Always set explicit max_tokens to avoid runaway costs (especially on reasoning models).
• Use stream: true for user-facing chat UIs to reduce perceived latency.
• Cache identical prompts for 5-60 seconds at the application layer to reduce token spend on retries.
• Implement exponential backoff with jitter for 429 and 5xx errors.
• Never put your API key in client-side code. Proxy through your backend.
• For long documents, prefer MiniMax-M3 or deepseek-v4-flash (1M context) over chunking.

Need help?

Email support@houjiayan.com or open a ticket in the dashboard. We respond within 24 hours on business days.