API documentation

OpenAI-compatible interface to 35 models from 7 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-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-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-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-flash",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

Anthropic Messages format

Alongside the OpenAI-compatible format, the gateway natively speaks Anthropic Messages — the two formats coexist, so use whichever your tooling expects. Same models, same balance. Tools built on the Anthropic SDK, like Claude Code, plug in directly.

Same base URL as the OpenAI format — only the path and headers differ:

POST https://api.houjiayan.com/v1/messages

cURL

curl https://api.houjiayan.com/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

Python (anthropic SDK)

from anthropic import Anthropic

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

message = client.messages.create(
    model="deepseek-flash",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)
print(message.content[0].text)

Claude Code

Claude Code works with any Anthropic-compatible endpoint. Point it at the gateway with two environment variables, then run claude as usual:

export ANTHROPIC_BASE_URL=https://api.houjiayan.com
export ANTHROPIC_AUTH_TOKEN=sk-hjy-...   # your platform API key

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-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-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-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-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-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.