API 文档

通过 OpenAI 兼容接口,访问来自 7 家上游厂商的 35 个模型。

5 分钟快速上手

从零到一次成功的 API 调用,只要 5 分钟。无需安装任何 SDK。

1. 创建账户

访问 api.houjiayan.com/register,需要邮箱地址,系统会发送验证链接。新账户注册即送 ¥6.6 赠金,无固定到期日,账户保持活跃即长期有效。

2. 生成 API Key

在 dashboard 里点击「添加新 token」。给它起个名字(例如「开发笔记本」)并复制 key —— 它只会显示一次。

3. 发起第一次调用

运行下面的 curl 命令,你应看到 JSON 响应中 assistant 角色包含一条「Hello!」消息。

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": "你好"}
    ]
  }'

不想自己挑模型?看智能路由 —— 把 model 设为 auto,交给网关来选。

主流客户端配置示例

常见 OpenAI 兼容客户端的复制即用配置。客户端之间唯一不同的是 Base URL 这一栏填什么 —— 每个都已标注精确值。

Python (openai SDK)

base_url 填完整 URL,含 /v1。

from openai import OpenAI

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

Node.js (openai SDK)

baseURL 填完整 URL,含 /v1。

import OpenAI from "openai";

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

LangChain(ChatOpenAI)

base_url 填完整 URL,含 /v1(旧版 LangChain 用 openai_api_base 参数)。

from langchain_openai import ChatOpenAI

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

print(llm.invoke("你好").content)

Cherry Studio

添加 OpenAI 兼容提供商,API 地址栏填完整 URL,含 /v1。

提供商类型 : OpenAI(OpenAI 兼容)
API 地址   : https://api.houjiayan.com/v1   ← 必须含 /v1
API 密钥   : sk-hjy-...
模型       : 按 ID 添加 —— 如 kimi-k2.6、deepseek-flash

NextChat / ChatGPT-Next-Web

自定义接口地址(BASE_URL)只填域名、不带 /v1 —— NextChat 会自己拼 /v1/chat/completions。这里填了 .../v1 会导致路径重复、请求失败。

自定义接口地址(BASE_URL): https://api.houjiayan.com   ← 只填域名,不带 /v1
API Key               : sk-hjy-...
自定义模型            : +kimi-k2.6,+deepseek-flash

OpenClaw

baseUrl 填完整 URL,含 /v1 —— OpenClaw 不会自动补。只填域名会打到网关的网页控制台,返回 HTTP 200 + HTML 页面而非 JSON;遇到这个症状先查这一栏。

baseUrl : https://api.houjiayan.com/v1   ← 必须含 /v1(不会自动补)
apiKey  : sk-hjy-...
model   : kimi-k2.6(或模型表中的任意 ID)

cURL

没有 Base URL 概念 —— 直接调用完整端点路径。

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": "你好"}
    ]
  }'

Anthropic Messages 格式

除 OpenAI 兼容格式外,网关还原生支持 Anthropic Messages 格式 —— 两种格式并存、可任选,同一批模型、同一个账户余额。Claude Code 等基于 Anthropic SDK 的工具可直接接入。

与 OpenAI 格式同一基准地址,仅路径与请求头不同:

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 支持任意 Anthropic 兼容端点。设置两个环境变量即可接入网关,之后正常使用 claude 即可:

export ANTHROPIC_BASE_URL=https://api.houjiayan.com
export ANTHROPIC_AUTH_TOKEN=sk-hjy-...   # 填你的平台 API Key

代码示例

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": "你好"}
    ]
  }'

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": "你好"}]
)
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: "你好" }]
});
console.log(response.choices[0].message.content);

流式响应(SSE)

设置 stream: true 即可逐 token 接收生成结果。每个分块是 server-sent event,带有 delta 字段。

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": "写一首关于 API 的俳句"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

函数调用

大多数模型支持 OpenAI 兼容的工具调用。在 tools 数组中定义你的工具,模型返回结构化的 tool_calls,你执行后将结果以 tool 角色消息回传。

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": "获取城市当前天气",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名"}
            },
            "required": ["city"]
        }
    }
}]

response = client.chat.completions.create(
    model="MiniMax-M2.7",
    messages=[{"role": "user", "content": "呼和浩特的天气怎么样?"}],
    tools=tools
)
tool_call = response.choices[0].message.tool_calls[0]
print(f"调用: {tool_call.function.name}({tool_call.function.arguments})")

错误码

• 401 API key 无效或缺失。检查 Authorization 头,确认 key 未被撤销。
• 402 余额不足。在 dashboard 充值,或如符合 24 小时窗口可申请退款。
• 403 API key 无权访问该模型,或账户因违反条款被暂停。
• 404 模型名不存在。调用 /v1/models 列出所有可用模型。
• 413 请求体过大。缩减 prompt 体积或换用更大上下文窗口的模型。
• 429 触发限流。网关会自动重试到其他上游(若可用)。如持续出现,见下方限流说明。
• 500/502/503/504 上游提供商错误。网关透传原始错误。换模型或指数退避后重试。
• 529 所有上游提供商都过载。网关无法完成请求,30 秒后重试。

限流策略

单用户限流:60 次/分钟,100K tokens/分钟(input + output 合计)。如果某个上游返回 429,网关会自动切换到同模型族的另一个提供商(若可用)。如需更高配额,请发邮件至 support@houjiayan.com 说明使用场景。

并发请求

每个 API key 最多 5 个并发进行中的请求。超出返回 429。如有批量需求,使用 /v1/batch 端点(2026 Q4 上线)。

最佳实践

• 始终显式设置 max_tokens,避免在推理模型上出现失控成本。
• 用户端聊天 UI 使用 stream: true,降低感知延迟。
• 在应用层对相同 prompt 缓存 5-60 秒,降低重试带来的 token 消耗。
• 对 429 与 5xx 错误实现带抖动的指数退避。
• 永远不要把 API key 放在客户端代码中,通过后端代理。
• 处理长文档时,优先选择 MiniMax-M3 或 deepseek-flash(1M 上下文),避免切块。

需要帮助?

发送邮件至 support@houjiayan.com,或在 dashboard 里开 ticket。工作时间 24 小时内回复。