# AI API Gateway 接入配置说明

更新时间：2026-09-07（全站配置说明统一来源）

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

**让 WorkBuddy 自动添加模型，请下载并只发送这份：[WorkBuddy 专用快速配置文档（17 个聊天模型，含批量合并代码）](https://gateway.dacongming.chat/workbuddy-quick-setup.md)。** 它明确每个字段和开关，先备份、保留已有配置，再逐项验收；不混入生图、生视频或服务器部署。本文保留其他客户端与多媒体接口说明。

## 先记住三项必填信息

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

> 客户端只使用网关生成的子 Key。不要把 Azure、Google Gemini 或 TokenHub 的主 Key 填到客户端。

## 个人 Token 看板

打开：<https://gateway.dacongming.chat/usage>

无需管理员登录，可以添加一个或多个完整子 Key：

1. 从“我的 Key”中按网关名称切换，例如“小兔0903”；
2. 查看该 Key 的额度、累计消耗、剩余额度和进度；
3. 选择今天、近 7 天、近 30 天或全部时间；
4. 在“模型汇总”和“每日汇总”中查看调用次数、Token 和估算金额。
5. 点击“模型标准价格表”，查看网关后台当前使用的单价、币种、有效期和计价档位。
6. 点击价格表旁的“模型接入配置说明”，在线阅读或下载本文。网关首页、管理员使用指南和看板都读取同一份文档，更新后重新打开即可看到最新内容。

看板只读，不会修改额度。完整 Key 只保存在当前浏览器的本地存储，不会写进网址或访问日志；重新打开页面可以继续使用。请只在个人设备上保存，并可随时单独删除或清空全部 Key。

Token 口径：Gemini 的输出包含思考消耗，不只是可见回复。新请求按上游返回的总 Token 记账，输出按“总数减输入”计算，金额使用价格表中的输出单价；不会关闭或限制思考。历史漏记数据不追补、不追加扣费。

## 选择正确的 Base URL

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

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

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

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

### WorkBuddy：按模型类别选择入口

WorkBuddy 使用两条接入路径：Azure GPT 使用专用协议桥；可用于聊天的 Gemini 和下文列出的 `tokenhub/...` 模型使用通用 OpenAI 兼容入口。具体配置见下一节。

### 其他入口速查

| 场景 | 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 专用快速配置文档](https://gateway.dacongming.chat/workbuddy-quick-setup.md)。交给 WorkBuddy 执行时只附专用文档，不要求它从本文自行筛选模型。

WorkBuddy 5.5.3 的“测试连接”固定请求 1 个输出 Token，低于 Azure Responses 的最低值 16。网关专用入口已仅对这一固定测试请求做兼容；仍会真实访问模型并按实际用量计费，不改变正常聊天的输出上限或思考设置。“连接成功”只代表基础连通，不代表所有工具、图片或参数组合都已验证。

## 当前正式环境支持的对话与 Agent 模型

下面只列对话与 Agent 模型。生图、生视频和实时音频使用独立接口，配置方式见后面的专门模块。

### Azure：固定部署

| 模型 ID | 状态 | 正确接口 |
| --- | --- | --- |
| `gpt-6-astra` | 已开通并实测 | 纯对话可用 Chat；工具调用使用 Responses 或 WorkBuddy 专用入口 |
| `gpt-5.6-sol` | 已开通并实测 | OpenAI Chat / Responses；支持 WorkBuddy 专用入口 |
| `gpt-5.6-terra` | 已开通并实测 | OpenAI Chat / Responses；支持 WorkBuddy 专用入口 |
| `gpt-5.6-luna` | 已开通并实测 | OpenAI Chat / Responses；支持 WorkBuddy 专用入口 |
| `gpt-realtime-whisper` | 已配置专用接口 | `wss://gateway.dacongming.chat/openai/v1/realtime?model=gpt-realtime-whisper` |

本表是已验证的部署名，新增 Azure 部署不会自动变成网关推荐配置。不要猜测模型别名；例如不能把 `gpt-6-astra` 简写成 `gpt-6`。

#### GPT-6 Astra 接入与计费

- 模型名填 `gpt-6-astra`。WorkBuddy 的 Base URL 填 `https://gateway.dacongming.chat/workbuddy/openai/v1`；支持原生 Responses 的客户端填 `https://gateway.dacongming.chat/openai/v1` 并选择 Responses 协议。
- 工具调用必须走 Responses（WorkBuddy 专用入口会自动转换）。不要通过普通 Chat 入口携带工具，不要设置 `reasoning_effort=none`、自定义 `temperature` 或 `top_p`。不主动关闭思考或缩短上下文、输出。
- WorkBuddy 专用入口会忽略该模型不支持的采样参数，保留思考强度和调用方明确设置的输出上限。连通测试通过不代表真实客户端的所有参数组合都兼容。
- 当前部署为 Azure **全局标准**。输入不超过 272,000 Token 使用短上下文价格；超过时，整次请求的输入、缓存和输出都使用长上下文价格。输出已包含思考，不再额外叠加思考 Token。
- 单价直接查看[模型标准价格表](https://gateway.dacongming.chat/usage)或[价格数据接口](https://gateway.dacongming.chat/api/usage/pricing)，与后台计费共用规则；本文不维护另一份数字价表。缓存读取、缓存写入分别计费，已包含在输入中的缓存不会重复按普通输入计费。
- 新请求记录 Token、金额并扣减对应额度；上线前未定价的历史请求不追扣费用。展示的是 Azure 公开标准价估算，不代替供应商最终账单。

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-你的子密钥",
    base_url="https://gateway.dacongming.chat/openai/v1",
)
response = client.responses.create(
    model="gpt-6-astra",
    input="用一句话介绍上海",
)
print(response.output_text)
```

[Azure 官方调用说明](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/reasoning#tool-calling-with-reasoning-models) · [Azure 全局标准价格来源](https://azure.microsoft.com/en-us/blog/gpt-6-astra-frontier-intelligence-for-work-now-generally-available-in-microsoft-foundry/)

### TokenHub：11 个已开通并实测的聊天模型

使用通用 Base URL 时保留 `tokenhub/` 前缀；使用 TokenHub 专用 Base URL 时去掉前缀。

| 通用 Base URL 使用的模型 ID | 主要用途 |
| --- | --- |
| `tokenhub/glm-5.3` | 中文综合、推理与 Agent |
| `tokenhub/glm-5.2` | 通用对话与推理 |
| `tokenhub/kimi-k3` | 长文档、长上下文、多模态与代码 |
| `tokenhub/kimi-k2.7-code` | 代码、截图和图文任务；temperature 兼容规则见下文 |
| `tokenhub/minimax-m3` | 长上下文、多模态与 Agent |
| `tokenhub/minimax-m2.7` | 通用推理与代码 |
| `tokenhub/deepseek-v4-pro` | 复杂推理与代码 |
| `tokenhub/deepseek-v4-pro-202606` | DeepSeek V4 Pro 指定版本 |
| `tokenhub/deepseek-v4-flash` | 高并发日常任务 |
| `tokenhub/deepseek-v4-flash-0731` | DeepSeek V4 Flash 指定版本 |
| `tokenhub/deepseek/deepseek-v4-flash-vision-exp` | 视觉理解实验版本 |

未开通的 TokenHub 型号不会展示在通用模型列表中。网关不会因 `no_official_price_rule` 阻止请求，但上游仍可能返回未开通、无配额或模型不存在。

### Gemini

| 模型 ID | 主要用途 | 正确接口 |
| --- | --- | --- |
| `gemini-3.1-pro-preview` | 复杂推理、长文档与重要任务 | 通用入口或 Gemini 原生 `generateContent` |
| `gemini-3.7-flash` | 日常多模态、代码和高频任务 | 通用入口或 Gemini 原生 `generateContent` |

Google 完整动态目录可通过 `/openai/v1/models` 或 `/v1beta/models` 查询；目录可见不等于支持所有调用方式。

## 常用模型怎么选

| 场景 | 优先模型 | 调用入口 |
| --- | --- | --- |
| 高难度推理、复杂代码与多步 Agent | `gpt-6-astra` | Responses；WorkBuddy 使用专用入口 |
| 复杂代码、深度推理、重要 Agent | `gpt-5.6-sol` | 通用入口或 WorkBuddy 专用入口 |
| 日常对话、内容、代码和自动化 | `gpt-5.6-terra` | 同上 |
| 批量分类、摘要、明确任务 | `gpt-5.6-luna` | 同上 |
| Google 复杂推理、长文档与重要任务 | `gemini-3.1-pro-preview` | 通用入口或 Gemini 原生 `generateContent` |
| Google 日常多模态、代码和高频任务 | `gemini-3.7-flash` | 同上 |
| 国产复杂推理、代码与重要 Agent | `tokenhub/deepseek-v4-pro-202606` | 通用入口；优先固定版本 |
| 国产低延迟视觉 Agent | `tokenhub/deepseek/deepseek-v4-flash-vision-exp` | 通用入口；WorkBuddy 可开图片输入 |
| 国产代码、截图和图文任务 | `tokenhub/kimi-k2.7-code` | 通用入口；WorkBuddy 可开图片输入 |
| 国产长代码、长文档和多模态 | `tokenhub/kimi-k3` | 通用入口；WorkBuddy 可开图片输入 |
| 国产中文综合任务 | `tokenhub/glm-5.3` | 通用入口 |
| 国产长上下文 Agent | `tokenhub/minimax-m3` | 通用入口 |
| 国产高并发、低成本任务 | `tokenhub/deepseek-v4-flash` | 通用入口 |

### 发挥模型完整能力

- 网关不会在客户端未填写时擅自补充或降低输出 Token 上限，模型使用自身默认能力。需要明确控制长度时，再按任务设置足够大的 `max_completion_tokens`、`max_tokens` 或 `max_output_tokens`，不要照搬几十或几百 Token 的连通性测试值。
- 流式 Chat 会自动向上游请求最终 usage，便于准确统计 Token 和费用；这不会降低推理强度或截断正文。
- `minimax-m3`、`minimax-m2.7` 在调用方没有显式选择时默认使用官方 `reasoning_split`；完整思考位于 `reasoning_content`，正文位于 `content`，调用方显式设置仍优先。
- 通用模型目录只展示当前服务器明确配置或在 TokenHub 控制台已开启的服务，不把整个平台目录误报为本账号可用模型。
- `tokenhub/kimi-k2.7-code` 上游当前只接受 `temperature=1`；网关会移除客户端附带的冲突值并使用模型原生默认值，不改变上下文、推理或输出能力。

## 生图模型：单独配置和调用

生图不要使用 `/chat/completions`。当前有两条独立路线。

### Nano Banana 2（推荐）

Nano Banana 不需要在本机或服务器单独安装。当前网关已经接入 Google Gemini，客户端按下面配置即可使用：

| 配置项 | 应填写什么 |
| --- | --- |
| 协议 | Gemini 原生 `generateContent` |
| Base URL | `https://gateway.dacongming.chat/v1beta` |
| API Key | 网关 `sk-...` 子 Key |
| 模型 ID | `gemini-3.1-flash-image` |
| 完整接口 | `POST /v1beta/models/gemini-3.1-flash-image:generateContent` |

Google 将该模型称为 Nano Banana 2；正式环境模型目录已确认可见。它支持文生图和图片编辑。

部署到客户端时：新建一个“Gemini 原生”提供商，填入上表的 Base URL 和子 Key，将默认模型设为 `gemini-3.1-flash-image`，保存后先用下面的最小请求生成一张图片。若客户端只有 OpenAI Chat 协议，不能部署该模型，请改用后面的 `gpt-image-2`。

```bash
curl -X POST \
  'https://gateway.dacongming.chat/v1beta/models/gemini-3.1-flash-image:generateContent' \
  -H 'Authorization: Bearer sk-你的子密钥' \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "parts": [{"text": "生成一张极简风格的未来城市海报，中文标题清晰可读"}]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"]
    }
  }'
```

生成结果位于 `candidates[].content.parts[].inlineData.data`，内容是 Base64 图片。图片编辑时，在 `parts` 中同时传入文字和图片的 `inlineData`。

### GPT Image 2

| 配置项 | 应填写什么 |
| --- | --- |
| 协议 | OpenAI Images API |
| Base URL | `https://gateway.dacongming.chat/openai/v1` |
| 模型 ID | `gpt-image-2` |
| 生图接口 | `POST /images/generations` |
| 编辑接口 | `POST /images/edits` |

```bash
curl -X POST 'https://gateway.dacongming.chat/openai/v1/images/generations' \
  -H 'Authorization: Bearer sk-你的子密钥' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-image-2",
    "prompt": "生成一张高质感的红色狐狸产品海报",
    "size": "1024x1024",
    "n": 1
  }'
```

编辑图片使用 multipart：

```bash
curl -X POST 'https://gateway.dacongming.chat/openai/v1/images/edits' \
  -H 'Authorization: Bearer sk-你的子密钥' \
  -F 'image=@image_to_edit.png' \
  -F 'model=gpt-image-2' \
  -F 'prompt=把背景改成黑色，保留主体不变'
```

只支持 OpenAI Chat 的客户端不能直接调用 Nano Banana；这类客户端使用 `gpt-image-2`，或改用支持 Gemini 原生 `generateContent` 的工具。

## 生视频模型：单独配置和调用

生视频不是 Chat Completions。当前有 Gemini Omni 和 MiniMax H3 两条路线。

### Gemini Omni Flash

| 配置项 | 应填写什么 |
| --- | --- |
| 协议 | Gemini Interactions API |
| 完整接口 | `https://gateway.dacongming.chat/v1beta/interactions` |
| 模型 ID | `gemini-omni-flash-preview` |

```bash
curl -X POST 'https://gateway.dacongming.chat/v1beta/interactions' \
  -H 'Authorization: Bearer sk-你的子密钥' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-omni-flash-preview",
    "input": "一架红色纸飞机掠过白色桌面，连续镜头",
    "response_format": {"type": "video", "delivery": "uri"}
  }'
```

返回 URI 后，从中取出 `FILE_ID`，继续使用同一个 Key 查询并下载：

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

curl -L 'https://gateway.dacongming.chat/v1beta/files/FILE_ID:download?alt=media' \
  -H 'Authorization: Bearer sk-你的子密钥' \
  -o output.mp4
```

### MiniMax Video H3

先提交异步任务，再用同一个子 Key 轮询。下面是最小付费验收示例；正式任务可使用 4–15 秒和 768P / 2K。

```bash
curl -X POST \
  'https://gateway.dacongming.chat/tokenhub/openai/v1/wand/minimax-video-v2/generation' \
  -H 'Authorization: Bearer sk-你的子密钥' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "minimax-video-h3",
    "content": [{"type": "text", "text": "一只橙色小猫在窗台上看向镜头"}],
    "resolution": "768P",
    "duration": 4,
    "ratio": "16:9"
  }'
```

将返回的 `task_id` 代入：

```bash
curl \
  'https://gateway.dacongming.chat/tokenhub/openai/v1/wand/minimax-video-v2/tasks/你的task_id' \
  -H 'Authorization: Bearer sk-你的子密钥'
```

每 3–5 秒查询一次。成功结果中的视频 URL 是临时地址，请及时下载。

## 给 AI / Agent 的调用规则

```text
1. 使用网关子 Key：Authorization: Bearer sk-...；绝不使用或索取服务端主 Key。
2. 一般 OpenAI 兼容调用的 base_url 是 https://gateway.dacongming.chat/openai/v1
3. GPT 模型名 gpt-6-astra、gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna 自动走 Azure。
4. gemini-* / gemma-* 自动走 Google；TokenHub 模型需写完整的 tokenhub/模型名。
5. WorkBuddy 中 gpt-6-astra 和三个 gpt-5.6 模型使用 https://gateway.dacongming.chat/workbuddy/openai/v1；
   Gemini 和 TokenHub 聊天模型使用 https://gateway.dacongming.chat/openai/v1。
   客户端会自动补 /chat/completions，接口地址只填 Base URL。
   GPT-6 Astra 的工具调用走 Responses 或该专用桥；不要设置 reasoning_effort=none、temperature、top_p。
6. WorkBuddy 中 TokenHub 工具调用使用自动工具选择，不要强制 required。图片输入仅为本轮实测通过的 Kimi K3、Kimi K2.7 Code 和 DeepSeek Flash Vision Exp 开启。
7. 生图和生视频必须使用本文的独立模块，不能当作 Chat Completions。
8. 先查询模型列表；付费的图片、视频和新模型先做小样本。
```

## 原始 HTTP 与 SDK 示例

```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": "用一句话介绍上海"}]
  }'
```

```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-你的子密钥'

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

## 常见错误对照

| 现象 | 常见原因 | 处理方式 |
| --- | --- | --- |
| `无效的 API 密钥` / 403 | 子 Key 写错、失效，或不允许对应供应商 | 使用生产网关中仍有效且权限匹配的子 Key |
| `410 Gone` | 仍在使用旧 `sslip.io` 地址 | 改为本文的 `https://gateway.dacongming.chat/...` 地址 |
| 旧 IP 的 `:5050` 入口 | 已恢复 `http://43.162.95.137:5050`，兼容现有服务，原 API 路径和 Key 不变 | HTTP 不加密，建议逐步迁移到本文的 HTTPS 地址；例如 `/workbuddy/openai/v1` 路径保持不变 |
| `resource_not_found` / 404 | 文件、上传会话或历史响应不属于当前 Key，或历史资源没有归属记录 | 使用创建该资源的 Key；旧文件重新上传，旧会话携带完整上下文重新开始 |
| `.../v1/v1/...` 或路径错误 | Base URL 后又被客户端追加 `/v1` | 只填写本文给出的 Base URL |
| WorkBuddy 工具调用或格式异常 | Azure GPT 与 TokenHub/Gemini 用错入口，或填写了完整 Chat 路径、开启了“自定义协议” | Azure GPT 使用专用入口；TokenHub/Gemini 使用通用入口；关闭“自定义协议” |
| DeepSeek 工具调用 400，提示思考模式不支持 `required` | 强制了 `tool_choice=required` | 改为自动工具选择 |
| WorkBuddy 上传图片后模型看不懂 | 图片开关、模型或输入格式不匹配 | 按专用文档核对图片开关；TokenHub 只为 Kimi K3、Kimi K2.7 Code、DeepSeek Flash Vision Exp 开启，Azure GPT 和两个 Gemini 聊天模型也开启；实际图片理解需单独验收 |
| 模型不存在或无法调用 | 模型名不可见，或 Key 没有对应提供商权限 | 查询 `/openai/v1/models` 后原样复制模型名 |
| 生图或生视频接口报错 | 错误使用 `/chat/completions` | 按本文独立的生图或生视频模块调用 |

## 额度与计费说明

非流式请求和异步视频任务会在调用上游前预留额度，成功后按实际用量结算；流式对话按上游实际用量结算，并发时可能略超额度。预留使用内部估算值，不会给模型追加较小的输出上限。流式 Chat 会自动请求 usage 元数据；客户端断开时，网关继续读取同一次请求的用量，不重新生成。若上游也中断且未返回用量，会记录异常，不编造账单。

上传文件、续传会话、存储的 Responses 和 Interactions 按创建它们的 Key 隔离，不能跨 Key 查看或引用。尚未实现资源隔离的上游管理接口不会直接透传；模型的对话、工具调用、思考与输出参数保持原有能力。

TokenHub 后付费模型按腾讯云广州公开价估算金额；DeepSeek V4 的特殊版本会按请求到达时的北京时间选择峰时或闲时价格。价格表升级可以补齐历史看板金额，但不会反向追扣 Key 的旧额度。图像、视频和新模型建议使用独立的金额额度 Key 先做小样本。看板金额是公开价格估算，不替代供应商最终账单。