dsh-freeapi-panel

Readme

# dsh-freeapi-panel

> **免费 API 聚合面板** —— 29 家正规免费 LLM provider，一键领 key、即配即用、自动故障转移。
> Free-API aggregator panel for [DeepSeek Harness](https://github.com/deepseek-ai/dsh).

---

## 它解决什么问题

想给自己的 agent 配几个备用模型，你得：

1. 一个个搜「哪家免费」
2. 一个个去官网注册、找 API key 页面
3. 记下每家的 base URL 和模型 ID
4. 手动填进配置

这个面板把前三步变成**卡片上的一个按钮**。

---

## 数据

目录来自开源项目 **[open-free-llm-api/awesome-freellm-apis](https://github.com/open-free-llm-api/awesome-freellm-apis)**（MIT，自报 495+ free LLM APIs / 30 providers）。

本地抽取脚本 `tools/extract-free-apis.cjs` 解析其 README 的四个锚点区块，产出 `data/free-api-catalog.json`：

```
<!-- BEGIN_PERMANENT_FREE -->   永久免费档
<!-- BEGIN_RENEWABLE -->         可再生额度
<!-- BEGIN_QUICK_REF -->         Base URL + 领 key 链接 + 是否要信用卡
<!-- BEGIN_BEST_MODELS -->       每家最佳免费模型 + Model ID + 上下文 + 限速
```

**30 家 provider / 29 家 base URL 可直接用 / 30 个免费模型（全部 OpenAI 兼容）**

按免费模型数排序的头部：

| Provider | 模型数 | Base URL |
|---|---|---|
| NVIDIA NIM | 132 | `https://integrate.api.nvidia.com/v1` |
| ModelScope | 61 | `https://api-inference.modelscope.cn/v1` |
| Cloudflare Workers AI | 40 | `https://api.cloudflare.com/client/v4/accounts/{id}/ai/run` |
| OpenRouter | 34 | `https://openrouter.ai/api/v1` |
| OpenCode Zen | 33 | `https://opencode.ai/zen/v1` |
| LLM7.io | 20 | `https://api.llm7.io/v1` |
| Google Gemini | 19 | `https://generativelanguage.googleapis.com/v1beta` |
| Groq | 12 | `https://api.groq.com/openai/v1` |

---

## 功能

### 卡片式配 key

每个 provider 一张卡：

- **`领 Key`** 按钮 → 直接跳官网申请页（`https://build.nvidia.com/settings/api-keys` 等）
- 密码框粘贴 key → 保存
- **`测试`** → 发一个最小 `chat/completions` 请求，告诉你到底行不行

错误信息是可读的，不是一串 HTTP 码：

| 状态 | 面板会告诉你 |
|---|---|
| `401` / `403` | key 无效或无权限 |
| `429` | key 有效，但被限速了 |
| `404` | 模型名或路径不对 |

### 自动故障转移

配好多家之后，`故障转移测试` 按你设定的优先级依次试，返回**第一个可用的** provider。

任何一家挂了不影响其他家，返回结果里带上每家的具体原因。

### 筛选

`全部` / `免信用卡` / `已配置` —— 没有信用卡也能跑起来。

---

## 安装

```sh
dsh plugin --profile web add github:qianai05233/dsh-freeapi-panel
```

重启 `dsh web`。右下角出现 `免费 API` 胶囊。

### 前置要求

- DSH `>= 0.1.7-rc.1`

---

## 安全

- **key 只存在本地**：`$DSH_HOME/storages/dsh-freeapi-panel/keys.json`（`mode 0600`）
- **面板只回掩码**：接口永远返回 `gsk_…_000` 这种形式，**绝不回明文**
- 所有请求直连各家官方端点，无中间代理

---

## 关于「白嫖」的边界

本项目**只整合正规免费额度** —— 官方公开的免费 tier、注册即送的额度、社区公开分发的 public key。

**不做、也建议你不要用**：

- ❌ 抓取 GitHub 上别人无意流露的密钥
- ❌ 对某个网站做「一键反代」绕过其访问控制

这类做法是**盗用他人凭据**和**绕过访问控制**，风险落在你自己的账号上（尤其是已连接 `repo` 全权限的 GitHub 账号）。上面这 29 家够用了。

---

## 重新生成目录

数据源更新后：

```sh
git clone --depth 1 https://github.com/open-free-llm-api/awesome-freellm-apis /tmp/freellm
node tools/extract-free-apis.cjs /tmp/freellm/README.md data/free-api-catalog.json
```

纯本地解析 markdown 表格，**零 token**。

---

## 配套

- **[dsh-codex-preset](https://github.com/qianai05233/dsh-codex-preset)** —— Codex 式五阶段工作流 agent preset
- **[dsh-codex-panel](https://github.com/qianai05233/dsh-codex-panel)** —— 悬浮控制面板，一键同意 git/GitHub 写操作

## License

MIT（本项目自身）。各 provider 的使用条款请遵循其官方网站。