零基础入门：先别急着写代码

第一次接触 API？没问题——这一节全程说人话，把该懂的词都讲明白。已经会用的同学，直接往下看端点详解。

API 是什么？——一家「自动点餐」的餐厅

想象一家餐厅：你（你的程序）写好一份点菜单（请求）递给服务员（API），服务员把单子送进后厨（AI 模型），做好菜再把结果（回复）端出来。你不需要知道后厨怎么炒的——会递单子、能接菜，就够了。API 就是这套「递单子 → 出菜」的规矩，大家按同一个规矩来，程序之间就能互相使唤。

API 网关是什么？——前台总服务台

DWON 就是那个前台。后面有十几家后厨（Nvidia、智谱、SiliconFlow、官方自营……几十个模型），但你只跟前台一个窗口打交道：报一个菜名（模型 ID），前台自动转给对应的后厨。菜名全部小写、不带商家前缀（比如 glm-4-flash、qwen3-8b），前台拿着菜名查自己的「菜单目录」，就知道该送往哪家后厨。

API Key（密钥）是什么？——一张随便领的门票

大部分网站的 API Key 像演唱会门票：要实名申请、要花钱、丢了要补办。而 DWON 是开放模式，Key 就是一张随便领的门票：你自己随手编一个就行（比如 sk-my-cat-123），填什么都能进门——不固定、不变更、不用申请、更不用来问任何人。唯一的要求：别空着。

一次调用的完整旅程

你的程序                          DWON 网关                        AI 模型（后厨）
   │                                 │                                │
   │  ① 递单子：带密钥的 HTTP 请求     │                                │
   │  「模型 deepseek-v4-flash，   │  ② 看菜名找后厨                 │
   │   用户问：你好」  ───────────────►│  查目录 → 官方自营后厨 ────────►│  ③ 思考并作答
   │                                 │                                │
   │  ④ 端菜：JSON 回复               │  ◄─────────────  原样转交        │
   │  「你好！很高兴见到你」 ◄─────────│                                │
   ▼

所以对接 DWON 你只需要记三样东西：① 接口地址（本站 https://api.dwon.de5.net/v1）；② 密钥（随便编）；③ 模型 ID（去「模型中心」抄）。往下看，三分钟跑通第一条请求。

三分钟跑通你的第一条请求

不用注册、不用充值、不用等审核。跟着做，三步出结果。

第 1 步：准备两样东西

• 接口地址：https://api.dwon.de5.net/v1（自部署的同学换成你自己的网关域名）
• 密钥：随手编一个，如 sk-hello-dwon——记住，填什么都能过

第 2 步：挑一种你喜欢的方式，复制 → 运行

方式一：命令行 curl（电脑自带，直接粘贴到终端）：

复制curl https://api.dwon.de5.net/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-hello-dwon" \
  -d '{"model": "glm-4-flash", "messages": [{"role": "user", "content": "用一句话介绍你自己"}]}'

方式二：Python（先 pip install openai）：

复制from openai import OpenAI

client = OpenAI(
    api_key="sk-hello-dwon",                              # 随便填，别空着就行
    base_url="https://api.dwon.de5.net/v1",                   # 注意结尾带 /v1
)
r = client.chat.completions.create(
    model="glm-4-flash",                            # 去模型中心随便抄一个
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)
print(r.choices[0].message.content)                       # 打印 AI 的回答

方式三：JavaScript / Node.js：

复制import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-hello-dwon",                                // 随便填
  baseURL: "https://api.dwon.de5.net/v1",                     // 结尾带 /v1
});
const r = await client.chat.completions.create({
  model: "glm-4-flash",
  messages: [{ role: "user", content: "用一句话介绍你自己" }],
});
console.log(r.choices[0].message.content);

第 3 步：看懂返回结果（每个字段是什么）

{
  "id": "chatcmpl-xxxx",          // 这次对话的编号（流水号，出问题反馈时报它）
  "model": "glm-4-flash",   // 实际干活的模型
  "choices": [{                    // 回答在这里（数组，一般只取第 0 个）
    "message": {
      "role": "assistant",         // 说话的人是 AI
      "content": "你好！我是智谱 GLM…"  // ★ 你要的答案就是它
    },
    "finish_reason": "stop"        // stop=正常说完；length=字数到上限被截断
  }],
  "usage": { ... }                 // 用量统计（本站免费，仅供参考）
}

新手最容易踩的三个坑

• base_url 忘了带 /v1：写成 https://api.dwon.de5.net 会 404。SDK 的 base_url 要以 /v1 结尾。
• 密钥填了空字符串：开放模式「填什么都过」，但空字符串等于没带门票。随便填点东西。
• 模型 ID 抄错：ID 要一字不差（区分大小写），拿不准就去「模型中心 · 模型列表」复制，或调 GET /v1/models 查。

跑通了？恭喜，你已经会用 80% 的功能了——剩下的端点全是「换个地址、换个参数」的重复动作。继续往下看概念词典和端点详解。

说人话 · 核心概念词典

对接时常见的专业术语，每个都用大白话+比喻讲一遍。看不懂某段文档时回来查这张表。

对话接口进阶：多轮对话、流式输出、参数速查

把 /v1/chat/completions 玩明白，等于会用了全部 AI 接口——其他端点都只是「换个地址、换个参数」。

参数速查表

多轮对话：为什么 AI 会「失忆」，怎么治

AI 没有记忆。每次调用都是一场全新的、没有前世记忆的对话——所谓多轮对话，就是你每次都把之前的完整聊天记录一起递回去，像复读整本笔记本：

复制# 第二轮提问时，messages 里要带上第一轮的全部内容：
messages = [
  {"role": "system",   "content": "你是一个耐心的编程老师"},   # 人设说明书
  {"role": "user",     "content": "Python 的列表是什么？"},       # 第 1 问
  {"role": "assistant", "content": "列表像一个能装任何东西的收纳盒…"}, # 第 1 答（也要带上！）
  {"role": "user",     "content": "那字典呢？"}                    # 第 2 问
]
r = client.chat.completions.create(model="glm-4-flash", messages=messages)

• AI 回答「失忆」了？九成是没把历史 messages 带回去。
• 记录太长会超出上下文窗口——常规做法：只带最近 10~20 条，或把更早的内容总结成一条。
• 「我不是、我没有」式人格漂移：在 system 里重申人设，或在每轮开头追加一条 system 提醒。

流式输出：做出「打字机」效果

请求里加 "stream": true，服务器就会通过 SSE 小水管一段段推送。每一段都是一个标准 JSON（data: {...}），你把 choices[0].delta.content 拼接到界面上即可：

复制# Python：一行开启流式
stream = client.chat.completions.create(
    model="glm-4-flash",
    messages=[{"role": "user", "content": "讲个冷笑话"}],
    stream=True,                          # ← 打字机开关
)
for chunk in stream:                      # 每次循环 = 一小段
    piece = chunk.choices[0].delta.content or ""
    print(piece, end="", flush=True)     # 逐段打印，肉眼可见的打字机

复制// JS（浏览器原生 SSE，无需任何库）
const res = await fetch("https://api.dwon.de5.net/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer sk-anything" },
  body: JSON.stringify({ model: "glm-4-flash", stream: true,
    messages: [{ role: "user", content: "讲个冷笑话" }] }),
});
const reader = res.body.getReader(), dec = new TextDecoder();
let buf = "", full = "";
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buf += dec.decode(value, { stream: true });
  const lines = buf.split("\n"); buf = lines.pop();
  for (const line of lines) {
    if (!line.startsWith("data: ")) continue;
    const data = line.slice(6);
    if (data === "[DONE]") break;        // 水管关闭信号
    const j = JSON.parse(data);
    full += j.choices[0].delta.content || "";
    // 每收到一段就把 full 更新到界面（如 box.textContent = full）→ 打字机效果
  }
}
console.log(full);

💡 本站「体验中心 · AI 对话」就是按这套逻辑实现的流式前端，可对照源码学习（仓库开源）。

GET/v1/models

获取可用模型列表。返回 Nvidia NIM、Gitee AI、SiliconFlow、智谱 GLM、讯飞星火与官方自营的全部模型。

响应结构

复制{"object": "list",
  "data": [{
    "id": "glm-4-flash",
    "object": "model",
    "owned_by": "zhipu"
  }]}

curl

复制curl https://api.dwon.de5.net/v1/models
  -H "Authorization: Bearer sk-****"

POST/v1/chat/completions

对话补全，支持流式（SSE）。根据填入的模型 ID 自动路由到对应上游。

请求体

复制{"model": "glm-4-flash",
  "messages": [
    {"role": "system", "content": "你是 DWON 助手"},
    {"role": "user", "content": "你好"}
  ],
  "temperature": 0.7,
  "stream": true  // 可选，流式返回
}

python

复制from openai import OpenAI
client = OpenAI(api_key="sk-****", base_url="https://api.dwon.de5.net/v1")
r = client.chat.completions.create(
  model="glm-4-flash",
  messages=[{"role": "user", "content": "你好"}])
print(r.choices[0].message.content)

POST/v1/embeddings

向量化。向量模型（如 bge-m3）由 Gitee AI / SiliconFlow 提供。

复制curl https://api.dwon.de5.net/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model": "bge-m3", "input": "DWON 网关"}'

POST/v1/rerank

重排。用于 RAG 检索结果排序，支持 bge-reranker-v2-m3 等重排模型。

复制curl https://api.dwon.de5.net/v1/rerank \
  -H "Content-Type: application/json" \
  -d '{"model": "bge-reranker-v2-m3", "query": "你好", "documents": ["A", "B"]}'

POST/v1/audio/transcriptions

语音识别（ASR）。使用 multipart/form-data 上传音频文件，内容类型透传；支持 glm-asr、sensevoice-small 等。

复制curl https://api.dwon.de5.net/v1/audio/transcriptions \
  -F "file=@audio.wav" \
  -F "model=glm-asr"

POST/v1/audio/speech

语音合成（TTS）。部分 TTS 模型的文本合成能力取决于上游平台；可携带 prompt_audio / prompt_audio_url 参考音频（语音克隆类模型）。

复制curl https://api.dwon.de5.net/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model": "spark-tts-0.5b", "input": "你好，欢迎使用 DWON"}'

POST/v1/moderations

内容安全检测。支持 qwen3guard-gen-0.6b、nonescape-v0、nsfw-classifier 等风控模型。

复制curl https://api.dwon.de5.net/v1/moderations \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3guard-gen-0.6b", "input": "待检测文本"}'

POST/v1/images/generations

文生图。由智谱 CogView 系列免费提供，模型 ID 如 cogview-3-flash。

复制curl https://api.dwon.de5.net/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{"model": "cogview-3-flash", "prompt": "一只坐在沙发上的橘猫", "size": "1024x1024"}'

POST/v1/videos/generations

文生视频。由智谱 CogVideoX 免费提供（如 cogvideox-flash）。视频生成耗时较长，客户端超时建议设置 5 分钟以上。

复制curl https://api.dwon.de5.net/v1/videos/generations \
  -H "Content-Type: application/json" \
  -d '{"model": "cogvideox-flash", "prompt": "一只小狗在草地上奔跑"}'

POST/v1/ip_location

IP 归属地查询。模型 ID 为 ip-location，由 Gitee AI 提供。

复制curl https://api.dwon.de5.net/v1/ip_location \
  -H "Content-Type: application/json" \
  -d '{"model": "ip-location", "ip": "8.8.8.8"}'

GET/assets/{key}

R2 媒体缓存访问。生成类接口（图片/音频/视频）产出的文件会写入缓存，可通过该路径直接访问，路径形如 /assets/{key}。

复制curl https://api.dwon.de5.net/assets/2026/08/abc123.png \
  -H "Authorization: Bearer sk-****"

特殊模型说明

• Auto 路由：填入 auto（旧写法 acu/auto-models 仍兼容），网关自动从 Nvidia 候选池随机命中一个主流模型。
• 智谱 GLM：模型 ID 如 glm-4-flash（直接用小写短 ID，无需前缀），含 CogView 绘图 / CogVideo 视频，同样免费。
• 讯飞星火：模型 ID 如 spark-lite，由科大讯飞免费提供。
• 官方自营：模型 ID 如 deepseek-v4-flash，由 DWON 官方自营旗舰通道提供，长期服务、稳定可靠。
• 自营排队：上游并发有限（全局 10 并发），高峰期会自动排队等待（先到先得，最长约 15 秒）；排队超时会返回 429 提示，请稍后重试，不要重复提交。
• 非标准端点：embedding / rerank / asr / tts 等特殊模型已适配为标准 OpenAI SDK 端点，可直接用官方 SDK 调用。
• 任意密钥可用：本站为开放模式，任意非空密钥均可调用（如 sk-****，中英文均可）——密钥不固定、不变更，填任何东西都会通过，无需申请、不用来问密钥。大版本更新与公告在 QQ 频道（频道号 pd57362562）通知。

错误与状态码

所有错误响应为结构化 JSON（非传统纯 HTTP 状态码机制）：程序识别主键是字符串业务错误码 error.code，同时保留数字 error.status（与 HTTP 状态码一致，兼容 OpenAI SDK）。中文消息 error.message 直接可读（Content-Type: application/json; charset=utf-8），并附带 QQ 频道 / 官网自助引导字段：

复制{"error": {
  "message": "上游限流或额度受限，请稍后重试或更换模型（上游说明：…）",
  "type": "dwon_api_error",
  "code": "RATE_LIMITED",
  "status": 429,
  "hint": "如需帮助：加入 QQ 频道 pd57362562（https://pd.qq.com/s/e4ktxw1b8）反馈，或访问官网 https://dwon.de5.net",
  "help": { "site": "https://dwon.de5.net", "docs": "https://dwon.de5.net/#/api",
            "qq_guild": "pd57362562", "qq_guild_url": "https://pd.qq.com/s/e4ktxw1b8",
            "qq_guild_invite": "公告与支持见 QQ 频道（频道号 pd57362562）；密钥无需申请，任意填即可用", "qq_group": 1103667832 }
}}

业务错误码（error.code）

每个错误响应均带 error.hint（加入 QQ 频道 pd57362562 与官网引导），程序可读取 error.help 结构化字段直接展示求助入口。

模型状态字段（/v1/models 返回）

健康评分（health.score）

每个模型附带近 100 次调用的健康评分（0-100，由成功率 / 延迟 / 稳定性加权计算）。90+ 优秀、70-89 良好、50-69 一般、<50 较差，可作为选择稳定模型的参考。

工具 API（/v1/tools/*）

不只 AI——网关同时开放纯算法工具 API（不消耗上游额度），鉴权与主 API 相同。工具箱页面的全部能力都可编程调用：

示例：curl https://你的网关/v1/tools/uuid -H "Authorization: Bearer sk-****"

开放数据与社区玩法 API

全站数据透明化 + 社区玩法——这部分端点大多无需密钥，欢迎拿去做监控面板、二次开发或装进你自己的项目。

数据大屏与用量

模型竞技场（盲测 + 投票 + 排行）

开发者小件

试一把：curl https://你的网关/v1/stats（不带密钥也能访问）。

对接指南：把 DWON 接进你的软件

DWON 说的是标准「OpenAI 方言」——凡是支持自定义 OpenAI 接口的软件（聊天客户端、翻译插件、IDE 编程助手、自动化工作流…）都能直接接。

通用三要素（所有软件都问这三样）

常见客户端配置示例

• ChatGPT Next Web（NextChat）：设置 → 自定义接口：API 地址填 https://api.dwon.de5.net（不带 /v1），API Key 随便填，模型手动输入模型 ID。
• LobeChat / Open WebUI：语言模型 → OpenAI 兼容：API 代理地址填 https://api.dwon.de5.net/v1（带 /v1），Key 随便填，添加模型 ID。
• 沉浸式翻译：翻译服务 → OpenAI：APIKEY 随便填，自定义模型接口地址 https://api.dwon.de5.net/v1/chat/completions（填到端点），模型填 ID。
• IDE 编程助手（Continue / Cline 等）：provider 选 openai，apiBase 填 https://api.dwon.de5.net/v1，apiKey 随便填，model 填 ID。
• 通用口诀：不确定带不带 /v1 时，两种都试一遍——反正密钥免费，试错零成本。

对接翻车对照表（症状 → 病因 → 处方）

FAQ：新手高频提问

点开看答案。没找到你的问题？QQ 群 1103667832 或频道 pd57362562 随时提问。