开发者文档 · 快速上手 / 接口参考

5 分钟快速上手

整个接入过程只有三步。下面以 Python 为例，其他语言的逻辑完全一致。

第 1 步：安装官方 SDK

直接使用 OpenAI 官方 SDK，不需要安装任何 GEEKHONER 专属依赖。

shell

pip install --upgrade openai

第 2 步：初始化客户端

把 base_url 指向 GEEKHONER 端点，api_key 换成控制台签发的密钥。

python

from openai import OpenAI

client = OpenAI(
    api_key="sk-gh-xxxxxxxxxxxxxxxx",
    base_url="https://aigateway.geekhoner.com/v1",
)

建议：不要把密钥硬编码在代码里。用环境变量 GEEKHONER_API_KEY 读取，并通过 OpenAI(api_key=os.environ["GEEKHONER_API_KEY"]) 注入。

第 3 步：发起第一次调用

python

resp = client.chat.completions.create(
    model="deepseek-flash",
    messages=[
        {"role": "user", "content": "用一句话介绍你自己"},
    ],
)

print(resp.choices[0].message.content)
print(resp.usage.total_tokens)   # Token 用量

运行成功后会输出模型回复，并带上本次消耗的 Token 总数。此时你就可以在控制台的用量看板里看到这条记录了。

鉴权与密钥管理

所有 API 请求都需要在 HTTP 头中携带 Bearer Token 进行鉴权。

http header

Authorization: Bearer sk-gh-9f2a1b3c4d5e6f7a8b9c0d1e2f3a7c41

密钥格式与作用域

前缀：GEEKHONER 密钥统一以 sk-gh- 开头，便于识别与泄露检测。
模型范围：创建密钥时可以限定可用模型列表，例如只允许客服机器人使用 DeepSeek 与 Qwen 系列。
额度上限：可以为每个密钥设置月度费用上限，超出后该密钥自动拒绝请求，防止意外超支。
随时禁用：怀疑泄露时可立即在控制台禁用，禁用即时生效，无需重启业务。

安全提醒：密钥等同于账户权限。请不要将其提交到 Git 仓库、写在客户端代码中，或通过聊天工具明文传递。发现泄露请第一时间在控制台禁用并重新签发。

密钥轮换建议

建议为不同环境（开发 / 测试 / 生产）使用独立密钥，并保持每 90 天轮换一次的节奏。轮换时先创建新密钥、灰度切换流量，确认无异常后再禁用旧密钥。

发起第一次调用

下面是一个完整的可运行示例，包含错误处理与重试建议。

python · 含错误处理

import os
import time
from openai import OpenAI, APIError, RateLimitError, APITimeoutError

client = OpenAI(
    api_key=os.environ["GEEKHONER_API_KEY"],
    base_url="https://aigateway.geekhoner.com/v1",
    timeout=60,
    max_retries=2,
)

def chat(prompt, model="deepseek-flash"):
    for attempt in range(3):
        try:
            return client.chat.completions.create(
                model=model,
                messages=[{"role": "user", "content": prompt}],
            )
        except (RateLimitError, APITimeoutError) as e:
            # GEEKHONER 网关内部已做通道级重试，此处为业务级兜底
            if attempt == 2:
                raise
            time.sleep(2 ** attempt)
        except APIError as e:
            print(f"调用失败: {e.status_code} {e.message}")
            raise

常见 AI 工具接入

如果你不打算写代码，只是想把手边的 AI 工具接到 GEEKHONER 上，看这一节就够了。下面按「桌面客户端 / 编程工具 / 平台与扩展」三类整理，每张卡片都给出必填配置、逐步操作与踩坑提醒。

通用规律：所有工具接入都只需要三样东西 —— 端点点选（ https://aigateway.geekhoner.com/v1）、控制台签发的 sk-gh- 密钥、以及 一个网关支持的模型 ID。区别只在于填写位置和地址要不要带 /v1。

API 地址到底该填什么

这是接入过程中最常见的失败原因：不同工具对地址的拼接方式并不统一。有的会自己补 /chat/completions，有的要求你填到接口为止。按用途对照下表填写即可。

三个高频错误：

地址多写 / 少写 /v1 —— 报 404。按上表对号入座，别凭记忆填。
模型 ID 与网关不一致 —— 报「模型不存在」。用 GET /v1/models 或控制台核对准确写法。
密钥里混入空格或换行 —— 报 401。重新从控制台复制，或换用卡片上的「复制」按钮。

如果目标工具不在这份清单里，只要它支持「自定义 OpenAI 兼容端点」或「OpenAI Compatible」，按上面的通用规律配置即可。仍然无法连通时，请记录客户端提示的状态码与 request_id，通过技术支持联系我们。

对话补全 `POST /v1/chat/completions`

这是最常用的接口，兼容 OpenAI Chat Completions 规范。

请求参数

参数	类型	必填	说明
model	string	是	模型 ID，如 `gpt-6.1-sol`、`deepseek-flash`
messages	array	是	对话消息列表，含 `role` 与 `content`
stream	boolean	否	是否流式返回，默认 `false`
temperature	number	否	采样温度，0–2，默认 1
max_tokens	integer	否	最大生成 Token 数
tools	array	否	函数调用工具定义（部分模型支持）
response_format	object	否	指定 JSON 输出格式（部分模型支持）

响应结构

json

{
  "id": "chatcmpl-zs-8f3a2b1c",
  "object": "chat.completion",
  "created": 1791234892,
  "model": "deepseek-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好，我是..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 26,
    "completion_tokens": 38,
    "total_tokens": 64
  }
}

消息角色说明

system：设定模型的人设与行为规则，通常放在首位。
user：用户输入内容。
assistant：模型的历史回复，用于多轮对话上下文拼接。
tool：函数调用的返回结果（使用 tools 时）。

流式输出（SSE）

设置 stream=true 后，服务端会以 Server-Sent Events 方式逐块返回内容，适合聊天类交互场景，能显著改善首屏体验。

python · 流式

stream = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[{"role": "user", "content": "写一段 200 字的开场白"}],
    stream=True,
)

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

注意：流式模式下 usage 字段通常只在最后一个 chunk 中出现。如果你需要精确统计 Token，请在流结束时读取最后一块的 usage，或直接以控制台账单为准（网关侧会独立统计，不受客户端影响）。

前端直连建议

生产环境不要把密钥放在前端。推荐做法是浏览器请求你自己的后端，由后端携带 GEEKHONER 密钥调用，再把 SSE 流转发回浏览器。这样密钥不会暴露在客户端，也便于你在后端做鉴权与限流。

向量化 `POST /v1/embeddings`

把文本转成向量，用于语义检索、聚类、去重与 RAG 知识库。

python

resp = client.embeddings.create(
    model="text-embedding-3-large",
    input=[
        "GEEKHONER 提供企业级 AI Token 供应服务",
        "大模型网关支持多通道容灾",
    ],
)

for item in resp.data:
    print(len(item.embedding))   # 向量维度

批量与维度

单次请求最多可传 96 条文本，超长文本会自动截断，建议先做文本切分。
默认输出 3072 维向量，部分模型支持通过 dimensions 参数降维以节省存储成本。
检索场景建议配合重排模型使用，能明显提升 RAG 命中准确率。

模型列表 `GET /v1/models`

获取当前账号可用的全部模型及其能力标签，便于在业务侧动态选择模型。

python

models = client.models.list()

for m in models.data:
    print(m.id)

# 输出示例：
# gpt-6.1-sol
# claude-sonnet-5-5
# deepseek-flash
# qwen3.8-max

完整模型与价格清单请见 Token 服务 · 模型价格表。

多模型路由与降级

这是 GEEKHONER 最有价值的部分：同一个模型请求，背后可能对应多条通道，网关会自动选出最合适的一条。

路由策略

成本优先：在满足质量要求的前提下，优先选择单位价格最低的可用通道。
延迟优先：优先选择近期 P95 延迟最低的通道，适合实时交互场景。
质量优先：优先选择能力最强、错误率最低的通道，适合复杂推理任务。
自研策略：企业版可基于请求标签（如业务线、用户等级）自定义路由规则。

自动降级链路

你可以为每个模型配置降级顺序。当主通道不可用时，请求会按顺序尝试后续通道，全部失败才返回错误。

控制台配置示例

主通道：  gpt-6.1-sol         → 官方直连（低延迟）
备通道1： gpt-6.1-sol         → 备用接入点
备通道2： claude-sonnet-5-5   → 同级别替代模型
备通道3： qwen3.8-max         → 国产替代（成本更低）

# 触发条件
# - 超时 > 30s
# - 连续 3 次 5xx
# - 错误率 > 5%（30 秒窗口）
# 切换耗时 ≤ 3s，业务无感

提示：降级到「同级别替代模型」时，输出风格可能与主模型有细微差异。如果你的业务对一致性要求极高，建议关闭跨模型降级，仅在同一模型的多条通道间切换。

配额、限流与计费

三级配额体系

账户级：整个账号的月度总预算，超出后所有请求被拒绝。
项目级：按业务项目划分的额度，便于成本归集与独立核算。
密钥级：单个 API Key 的额度上限，适合隔离不同团队或环境。

限流规则

限流按 QPS（每秒请求数）与 TPM（每分钟 Token 数）双维度控制。超出限制时返回 429，建议客户端做指数退避重试。

http 响应头

X-ZS-RateLimit-Limit:     2000
X-ZS-RateLimit-Remaining: 1783
X-ZS-RateLimit-Reset:     1791234900
X-ZS-Quota-Remaining:     842.35      # 剩余额度（元）
X-ZS-Channel:             cn-east-2   # 本次实际走的通道
X-ZS-Upstream-Latency:    638         # 上游耗时（毫秒）

计费口径

计费以网关侧统计为准，与官方口径保持一致：输入 Token 按输入价计费，输出 Token 按输出价计费。推理类模型的思考过程 Token 计入输出。

计费公式：费用 =（输入 Token ÷ 1,000,000）× 输入单价 +（输出 Token ÷ 1,000,000）× 输出单价，再乘以当前档位的折扣系数。

审计日志与合规

每一次调用都会在网关侧记录调用明细，用于账单核对与问题排查。

日志字段

字段	说明
request_id	全局唯一请求 ID，可用于问题定位
api_key_name	发起请求的密钥名称（不记录密钥明文）
model / channel	请求模型与实际命中的通道
prompt / response	提示词与模型响应内容
usage	输入 / 输出 / 总 Token 数
latency	网关总耗时与上游耗时
cost	本次调用费用（含折扣后）
status	HTTP 状态码与上游错误原因

查询与导出

支持按时间范围、模型、密钥、状态码组合检索，结果可导出 CSV。
支持请求回放：用历史请求的参数重新发起调用，便于复现问题。

数据使用承诺：GEEKHONER 不会将客户的请求与响应内容用于任何模型训练。

多语言 SDK 示例

所有语言都直接使用各家官方 SDK，只需要替换端点与密钥。

Node.js

javascript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.GEEKHONER_API_KEY,
  baseURL: "https://aigateway.geekhoner.com/v1",
});

const stream = await client.chat.completions.create({
  model: "gemini-3.8-flash",
  messages: [{ role: "user", content: "你好" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Java

java · okhttp

String json = """
    {
      "model": "qwen3.8-max",
      "messages": [{"role": "user", "content": "你好"}]
    }
    """;

Request request = new Request.Builder()
    .url("https://aigateway.geekhoner.com/v1/chat/completions")
    .addHeader("Authorization", "Bearer " + System.getenv("GEEKHONER_API_KEY"))
    .addHeader("Content-Type", "application/json")
    .post(RequestBody.create(json, MediaType.parse("application/json")))
    .build();

try (Response response = client.newCall(request).execute()) {
    System.out.println(response.body().string());
}

PHP

php · curl

$ch = curl_init('https://aigateway.geekhoner.com/v1/chat/completions');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('GEEKHONER_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'glm-5.3',
        'messages' => [['role' => 'user', 'content' => '你好']],
    ]),
]);

$result = curl_exec($ch);
curl_close($ch);
echo $result;

错误码对照表

网关在透传上游错误的同时，会补充自己的错误说明。建议按状态码做分类处理。

状态码	含义	处理建议
200	调用成功	正常处理响应内容
400	请求参数错误	检查 model 是否可用、messages 格式是否正确
401	鉴权失败	密钥错误、已禁用或已过期，请检查 Authorization 头
403	无权限	该密钥未授权使用此模型，请在控制台调整模型范围
429	触发限流 / 余额不足	指数退避重试；余额不足请及时充值
500	上游服务异常	网关已自动重试与切换通道，仍失败请携 request_id 联系支持
503	服务暂不可用	该模型全部通道异常，建议降级到替代模型
504	上游超时	适当增大 timeout，或改用延迟更低的模型

错误响应示例

json

{
  "error": {
    "message": "Rate limit exceeded for key '客服机器人'",
    "type": "rate_limit_error",
    "code": "quota_exceeded",
    "request_id": "req-zs-7d2f9a1b",
    "retry_after": 3
  }
}

排查建议：遇到任何异常，请先记录响应中的 request_id。凭这个 ID 我们可以在审计日志里定位到这一次调用的全部细节，包括实际上游、耗时与错误原因。

从官方渠道迁移

如果你已经在用官方 API，迁移到 GEEKHONER 通常只需要改两个配置项，业务代码零改动。

迁移检查清单

替换 base_url：从 https://api.openai.com/v1 改为 https://aigateway.geekhoner.com/v1。
替换 api_key：换成控制台签发的 sk-gh- 密钥。
核对模型 ID：GEEKHONER 的模型 ID 与官方保持一致，无需修改。
检查超时设置：建议 timeout 不低于 60 秒，以避免长文本生成被中断。
灰度切流：先切 5% 流量观察一天，确认成功率与延迟正常后再全量。
保留回滚能力：把官方配置保留在环境变量中，便于快速切回。

Anthropic 协议迁移

如果你用的是 Anthropic 官方 SDK，GEEKHONER 同样提供兼容端点，把 base_url 指向 https://aigateway.geekhoner.com 即可。

python · anthropic sdk

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-gh-xxxxxxxxxxxxxxxx",
    base_url="https://aigateway.geekhoner.com",
)

msg = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)

print(msg.content[0].text)

迁移服务：企业版客户可以申请免费的迁移支持。我们会帮你做兼容性测试、压测对比与灰度方案设计，确保切换过程平滑。

5 分钟从零到第一个请求

5 分钟快速上手

第 1 步：安装官方 SDK

第 2 步：初始化客户端

第 3 步：发起第一次调用

鉴权与密钥管理

密钥格式与作用域

密钥轮换建议

发起第一次调用

常见 AI 工具接入

API 地址到底该填什么

对话补全 POST /v1/chat/completions

请求参数

响应结构

消息角色说明

流式输出（SSE）

前端直连建议

向量化 POST /v1/embeddings

批量与维度

模型列表 GET /v1/models

多模型路由与降级

路由策略

自动降级链路

配额、限流与计费

三级配额体系

限流规则

计费口径

审计日志与合规

日志字段

查询与导出

多语言 SDK 示例

Node.js

Java

PHP

错误码对照表

错误响应示例

从官方渠道迁移

迁移检查清单

Anthropic 协议迁移

对话补全 `POST /v1/chat/completions`

向量化 `POST /v1/embeddings`

模型列表 `GET /v1/models`