From 066ceb823e21e5776a6977ae1ea8ec20a021b9de Mon Sep 17 00:00:00 2001 From: kone Date: Wed, 13 May 2026 19:22:11 +0800 Subject: [PATCH] chore: prepare 0.1.130 release --- backend/cmd/server/VERSION | 2 +- frontend/public/docs/api.html | 680 ++++++++++++++++++++++++++++++++++ 2 files changed, 681 insertions(+), 1 deletion(-) create mode 100644 frontend/public/docs/api.html diff --git a/backend/cmd/server/VERSION b/backend/cmd/server/VERSION index aab9b571..d0c4abc6 100644 --- a/backend/cmd/server/VERSION +++ b/backend/cmd/server/VERSION @@ -1 +1 @@ -0.1.129 +0.1.130 diff --git a/frontend/public/docs/api.html b/frontend/public/docs/api.html new file mode 100644 index 00000000..85bd9526 --- /dev/null +++ b/frontend/public/docs/api.html @@ -0,0 +1,680 @@ + + + + + + API 使用文档 + + + +
+
+
API Gateway Docs
+

大模型 API 使用文档

+

+ 这是面向当前站点用户的接入说明页。页面内容按 OpenAI 兼容网关的常见用法组织，适合挂在“系统设置 -> 通用设置 -> 文档链接”或“自定义菜单”中直接访问。 +

+
+
+
推荐访问路径
+
/docs/api.html
+
+
+
默认协议
+
Bearer API Key
+
+
+
兼容方向
+
OpenAI / Claude Code / Gemini CLI / Codex CLI
+
+
+
+ +
+ + +
+
+

接入概览

+

+ 用户先在平台生成 API Key，再通过 OpenAI 兼容地址访问上游模型。站点实际域名、默认 Base URL、自定义端点由管理员在“系统设置 -> 通用设置”中维护，这个页面只负责给出固定的使用范式。 +

+
+
+

认证方式

+

所有请求统一使用 Authorization: Bearer YOUR_API_KEY。

+
+
+

常用入口

+

推荐默认 OpenAI 兼容路径：/v1/chat/completions。

+
+
+
+ 页面不直接写死你的正式域名。部署后建议把“文档链接”设置为完整地址，例如 https://your-domain.com/docs/api.html，这样头部文档按钮和自定义菜单都会跳转到这个静态页。 +
+
+ +
+

接口路径

+

+ 下表给出常见兼容路径。默认情况下，站点会把这些路径代理到对应上游模型服务。 +

+
+
+ OpenAI 兼容 + https://your-domain.com/v1/chat/completions +
+
+ Gemini 兼容 + https://your-domain.com/v1beta +
+
+ Claude Code / Anthropic + https://your-domain.com +
+
+ Antigravity 专用 + https://your-domain.com/antigravity +
+
+
+ +
+

HTTP 调用示例

+

+ 业务系统、脚本和第三方客户端优先使用 OpenAI 兼容格式，兼容性最好。 +

+
+
+ cURL: Chat Completions + /v1/chat/completions +
+ 
curl https://your-domain.com/v1/chat/completions \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gpt-5.4",
+    "messages": [
+      {"role": "system", "content": "You are a helpful assistant."},
+      {"role": "user", "content": "请简要介绍这个 API 网关"}
+    ]
+  }'
+
+
+
+ cURL: 流式输出 + "stream": true +
+ 
curl https://your-domain.com/v1/chat/completions \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gpt-5.4",
+    "stream": true,
+    "messages": [
+      {"role": "user", "content": "生成一个三点行动计划"}
+    ]
+  }'
+
+
+ +
+

SDK 示例

+

+ 只要 SDK 支持自定义 base_url 或 baseURL，通常都能平滑接入。 +

+
+
+
+ JavaScript + openai npm +
+ 
import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: process.env.API_KEY,
+  baseURL: "https://your-domain.com/v1",
+});
+
+const res = await client.chat.completions.create({
+  model: "gpt-5.4",
+  messages: [{ role: "user", content: "Hello" }],
+});
+
+console.log(res.choices[0]?.message?.content);
+
+
+
+ Python + openai python +
+ 
from openai import OpenAI
+
+client = OpenAI(
+    api_key="YOUR_API_KEY",
+    base_url="https://your-domain.com/v1",
+)
+
+res = client.chat.completions.create(
+    model="gpt-5.4",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+
+print(res.choices[0].message.content)
+
+
+
+ +
+

CLI 配置

+

+ 如果你的用户主要通过 Claude Code、Gemini CLI、Codex CLI 或 OpenCode 接入，可以直接参考下面的环境变量和配置示例。 +

+
+
+
+ Claude Code + Anthropic 风格 +
+ 
export ANTHROPIC_BASE_URL="https://your-domain.com"
+export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
+export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
+
+
+
+ Gemini CLI + Gemini 风格 +
+ 
export GOOGLE_GEMINI_BASE_URL="https://your-domain.com/v1beta"
+export GEMINI_API_KEY="YOUR_API_KEY"
+export GEMINI_MODEL="gemini-2.0-flash"
+
+
+
+ Codex CLI + ~/.codex/config.toml +
+ 
model_provider = "OpenAI"
+model = "gpt-5.4"
+disable_response_storage = true
+network_access = "enabled"
+
+[model_providers.OpenAI]
+name = "OpenAI"
+base_url = "https://your-domain.com/v1"
+wire_api = "responses"
+requires_openai_auth = true
+
+
+
+ OpenCode + opencode.json +
+ 
{
+  "provider": {
+    "openai": {
+      "options": {
+        "baseURL": "https://your-domain.com/v1",
+        "apiKey": "YOUR_API_KEY"
+      }
+    }
+  },
+  "model": "openai/gpt-5.4"
+}
+
+
+
+ +
+

兼容格式

+

+ 这个站点本质上是统一网关，所以文档应重点说明“按什么协议接入”，而不是只强调某一家模型。 +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
类型适用场景关键路径 / 变量
OpenAI Chat Completions网页、服务端、脚本、第三方 SDK/v1/chat/completions
Responses / CodexCodex CLI、支持 responses 的客户端base_url=/v1
Anthropic / ClaudeClaude CodeANTHROPIC_BASE_URL
GeminiGemini CLI、Gemini 兼容调用GOOGLE_GEMINI_BASE_URL
+
+
+ +
+

常见问题

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
状态码说明
401API Key 缺失、错误或已失效。先检查 Bearer Token。
403密钥被禁用、IP 限制未通过，或当前分组无权限。
404请求路径错误，常见于把 /v1、/v1beta 写错。
429触发速率限制或额度限制，可去 API Key 页面看用量窗口。
5xx网关或上游临时异常，建议稍后重试并检查后台账号状态。
+
+
+ 如果你希望这个静态页显示你自己的域名、默认模型、品牌名，可以后续再把它改成读取运行时配置的版本。但按你当前要求，静态 HTML 更简单，也最适合挂到“文档链接”里。 +
+
+
+
+ +
+ 静态文档地址：/docs/api.html +
+
+ +