# AI API Gateway 接入配置说明

更新时间：2026-09-01

这份文档既可直接给人配置，也可交给 AI / Agent 按规则调用。它只说明客户端需要填写的地址、鉴权方式和模型名；不要把任何主 Key、数据库文件或服务端环境变量交给客户端。

## 先记住三项必填信息

每个 OpenAI 兼容客户端通常只需要下面三项：

| 配置项 | 应填写什么 |
| --- | --- |
| **Base URL / 接口地址** | 按场景从下方复制；这里填写的是**根地址**，不是完整的 `/chat/completions` 地址 |
| **API Key** | 网关管理后台创建的、仍有效的 `sk-...` 子 Key |
| **模型名称 / Model ID** | 例如 `gpt-5.6-luna`；从模型列表原样复制，不加空格或 `models/` 前缀 |

> 统一使用 HTTPS 网关：`https://gateway.dacongming.chat`。不要把 Azure、Google Gemini 或 TokenHub 的主 Key 填到客户端。旧 IP 地址仅保留兼容，不再作为新配置使用。

## 选择正确的 Base URL

### 大多数 OpenAI 兼容客户端

适用于聊天、代码、文本、图片理解、普通工具调用等。

```text
https://gateway.dacongming.chat/openai/v1
```

客户端会自行请求 `/chat/completions` 或 `/responses`。不要再手动拼一个 `/v1`，否则会变成错误的重复路径。

### WorkBuddy：请使用下面的独立模块

WorkBuddy 需要协议桥来同时兼容推理与工具调用，不能使用上面的通用地址。请直接看本文的「WorkBuddy 配置」章节。

### 其他入口速查

| 场景 | 应复制的 Base URL / 完整入口 | 备注 |
| --- | --- | --- |
| 固定使用 TokenHub | `https://gateway.dacongming.chat/tokenhub/openai/v1` | 模型名用 TokenHub 原始名 |
| Gemini 原生 SDK（生图、TTS、Embedding 等） | `https://gateway.dacongming.chat/v1beta` | 模型名使用 `gemini-...` |
| Gemini 原生文件上传 | `https://gateway.dacongming.chat/upload/v1beta/files` | 文件 API 专用完整入口 |
| MiniMax H3 视频生成 | `https://gateway.dacongming.chat/tokenhub/openai/v1/wand/minimax-video-v2/...` | 这是异步视频接口，不是 Chat Completions |

## WorkBuddy 配置（单独使用本节）

在 WorkBuddy 的「编辑模型」页面按以下内容填写：

| WorkBuddy 字段 | 正确值 |
| --- | --- |
| 提供商 | `自定义 / Custom` |
| **接口地址** | `https://gateway.dacongming.chat/workbuddy/openai/v1` |
| API Key | 有效的网关 `sk-...` 子 Key |
| 模型名称 | `gpt-5.6-sol`、`gpt-5.6-terra` 或 `gpt-5.6-luna` |

### WorkBuddy 的两个关键规则

1. **接口地址不要填写** `.../chat/completions`。WorkBuddy 会自动在上面的 Base URL 后追加该路径。
2. 使用 `https://gateway.dacongming.chat` 这套 HTTPS 地址；不要再把旧 IP 地址用于新配置。

### WorkBuddy 高级配置

- 勾选：`工具调用`、`思考模式`
- 可按需要勾选：`图片输入`、`允许关闭思考`
- 不要勾选：`仅思考模式`、`自定义协议`

WorkBuddy 会将自己的 Chat Completions 请求转换为 Azure Responses 请求，处理工具调用、推理强度和工具结果回传。因此只要使用 WorkBuddy，就必须走这个专用 Base URL。

### WorkBuddy 配置示例

```text
接口地址： https://gateway.dacongming.chat/workbuddy/openai/v1
API Key：   sk-你的有效子密钥
模型名称：  gpt-5.6-luna
```

保存后点击「测试连接」。若显示“API Key 无效或没有权限访问该模型”，请换成线上生产网关中仍有效、且允许 Azure / 通用调用的子 Key；模型名或勾选项不能修复失效 Key。

## 常用模型怎么选

| 场景 | 优先模型 | 调用入口 |
| --- | --- | --- |
| 复杂代码、深度推理、重要 Agent | `gpt-5.6-sol` | OpenAI 兼容 Base URL 或 WorkBuddy 专用 Base URL |
| 日常对话、内容、代码和自动化 | `gpt-5.6-terra` | 同上 |
| 批量分类、摘要、明确且可重复的任务 | `gpt-5.6-luna` | 同上 |
| 通用多模态、复杂 Agent | `gemini-3.7-flash` | 通用 OpenAI 兼容 Base URL |
| 日常 Gemini 多模态 | `gemini-3.6-flash` | 通用 OpenAI 兼容 Base URL |
| 低成本批量 Gemini | `gemini-3.5-flash-lite` | 通用 OpenAI 兼容 Base URL |
| 国产通用 / 中文批量任务 | `tokenhub/glm-5.3-flash` | 通用 OpenAI 兼容 Base URL |

模型目录会随上游变化。对新模型、图像、视频或付费批量任务，先查询当前 Key 可见模型并做小样本验证。

## 给 AI / Agent 的调用规则

将以下规则原样提供给需要调用网关的 AI：

```text
1. 使用网关子 Key：Authorization: Bearer sk-...；绝不使用或索取服务端主 Key。
2. 一般 OpenAI 兼容调用的 base_url 是
   https://gateway.dacongming.chat/openai/v1
3. GPT 模型名 gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna 自动走 Azure。
4. gemini-* / gemma-* 模型自动走 Google；TokenHub 模型需写 tokenhub/模型名。
5. WorkBuddy 只能使用
   https://gateway.dacongming.chat/workbuddy/openai/v1
   并由客户端自动补 /chat/completions；不要在接口地址字段填完整路径。
6. Gemini 原生生图、TTS、Embedding 等使用 /v1beta，不要伪装为 Chat Completions。
7. 先调用模型列表确认模型和 Key；对会产生费用的请求先做小样本。
```

## 原始 HTTP 与 SDK 示例

只有手写 HTTP 请求时，才在 Base URL 后明确加接口路径：

```bash
curl https://gateway.dacongming.chat/openai/v1/chat/completions \
  -H 'Authorization: Bearer sk-你的子密钥' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5.6-luna",
    "messages": [{"role": "user", "content": "用一句话介绍上海"}]
  }'
```

使用 OpenAI SDK 时，只填写 Base URL：

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-你的子密钥",
    base_url="https://gateway.dacongming.chat/openai/v1",
)

response = client.chat.completions.create(
    model="gpt-5.6-luna",
    messages=[{"role": "user", "content": "你好"}],
)
```

## 先验证 Key 与模型

下面的请求只检查鉴权和可见模型，不会发起一次文本生成：

```bash
curl https://gateway.dacongming.chat/openai/v1/models \
  -H 'Authorization: Bearer sk-你的子密钥'
```

Gemini 原生模型目录：

```bash
curl https://gateway.dacongming.chat/v1beta/models \
  -H 'Authorization: Bearer sk-你的子密钥'
```

## 常见错误对照

| 现象 | 常见原因 | 处理方式 |
| --- | --- | --- |
| `无效的 API 密钥` / 403 | 子 Key 写错、已失效，或 Key 来自另一套网关 | 在生产网关后台创建或取得当前有效的 `sk-...` 子 Key，再重新保存 |
| `.../v1/v1/...` 或路径错误 | Base URL 后又被客户端追加了 `/v1` | 只填写本文给出的 Base URL |
| WorkBuddy 无法工具调用或格式异常 | 使用了通用入口、填了完整 Chat 路径，或勾选了“自定义协议” | 使用 WorkBuddy 专用模块的配置 |
| 模型不存在或无法调用 | 模型名不是当前 Key 可见的模型，或该 Key 不具备对应提供商权限 | 用 `/openai/v1/models` 查询后原样复制模型名 |
| Gemini 原生能力报接口错误 | 把原生模型放进了 OpenAI Chat Completions | 改用 `/v1beta` 对应的 Gemini 原生接口 |

## 额度与计费说明

有限额度子 Key 会在调用上游前预留额度，成功后再按实际 Token 结算；失败会释放预留。模型列表验证不会发起付费生成。图像、视频和新模型请使用独立的金额上限子 Key 先做小样本验收。