README.md

---
title: ONYX
emoji: "🚀"
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
---

# onyx2api

把 [Onyx Cloud](https://cloud.onyx.app) 包装成标准的 OpenAI / Anthropic API，Go 写的，单文件，零依赖，编译出来就一个二进制。

说白了：你有 Onyx 的 Key，这东西帮你把它变成任何支持 OpenAI 或 Anthropic 协议的客户端都能直接用的接口。ChatGPT-Next-Web、LobeChat、Cursor、随便什么客户端，填个地址就能连。

> [!NOTE]
> 仅供学习和技术研究，请遵守 Onyx 使用条款及当地法律法规。

## 跑起来

三种方式，挑一个适合自己的。

### 直接编译运行

```bash
git clone https://github.com/smysle/onyx2api-go.git
cd onyx2api-go
go build -o onyx2api .

ONYX_KEYS="on_tenant_xxx" CLIENT_API_KEY="sk-456789" ./onyx2api
```

默认监听 `0.0.0.0:9898`，想换端口就加个 `PORT=7860`。

### Docker

```bash
docker build -t onyx2api:latest .
docker run --rm -p 7860:7860 \
  -e PORT=7860 \
  -e ONYX_KEYS=on_tenant_xxx \
  -e CLIENT_API_KEY=sk-456789 \
  onyx2api:latest
```

镜像用的 distroless，编译产物就几 MB，启动秒开。

### 丢到 Hugging Face Spaces

最省事的部署方式，白嫖 HF 的容器，不用自己搞服务器。

参考实例：`https://huggingface.co/spaces/smyslenny/ONYX`（可以直接 Duplicate）

**步骤：**

1. 把代码推到你自己的 Space：

```bash
git clone https://github.com/smysle/onyx2api-go.git
cd onyx2api-go
git remote add hf https://huggingface.co/spaces/<你的用户名>/ONYX
git push hf main
```

如果要求输密码，Username 填 HF 用户名，Password 填 Access Token（要有 write 权限）。

2. 去 Space 的 **Settings → Variables and secrets** 里加两个 Secret：

   - `ONYX_KEYS` = 你的 Onyx Key（多个用逗号隔开）
   - `CLIENT_API_KEY` = 自己定一个密钥，给客户端用的

3. 等它 Build 完，接口地址就是 `https://<你的用户名>-onyx.hf.space/v1`

> [!TIP]
> 别人 Duplicate 你的 Space 也能用，但 Secret 不会跟过去，得自己配。

## 它能干什么

**双协议兼容** — 同时暴露 OpenAI 和 Anthropic 两套接口，一个服务顶两个用：

- `POST /v1/chat/completions` — OpenAI 格式，`Authorization: Bearer xxx` 鉴权
- `POST /v1/messages` — Anthropic 格式，`x-api-key: xxx` 鉴权

两个接口都支持流式（SSE）和非流式响应。

**多 Key 轮询** — `ONYX_KEYS` 里填多个 Key（逗号分隔），请求会自动轮着用，原子操作无锁，不会有并发问题。

**自动重试** — 遇到 502 / 503 / 504 / 429 会自动重试，最多 3 次，间隔 2s → 5s → 10s 递增。重试时还会自动换 Key（如果有多个的话）。

**Reasoning 透传** — Onyx 返回的推理过程（thinking）会被正确翻译。OpenAI 格式走 `reasoning_content` 字段，Anthropic 格式走 `thinking` content block，下游客户端能正常展示思考链。

**工具调用可视化** — Onyx 的搜索、网页抓取、代码执行、图片生成、深度研究等工具事件，都会被转成可读的文本块插入回复里，不会丢失上下文。

## 接口一览

| 方法 | 路径 | 用途 |
|------|------|------|
| `GET` | `/` | 服务信息，返回版本号和接口列表 |
| `GET` | `/health` | 健康检查，顺便告诉你加载了几个 Key |
| `GET` | `/v1/models` | 模型列表（OpenAI 格式） |
| `POST` | `/v1/chat/completions` | OpenAI 兼容接口 |
| `POST` | `/v1/messages` | Anthropic 兼容接口 |

### 用 curl 试一下

健康检查：

```bash
curl http://127.0.0.1:9898/health
# {"status":"ok","version":"0.5.0","keys":1}
```

OpenAI 格式：

```bash
curl http://127.0.0.1:9898/v1/chat/completions \
  -H "Authorization: Bearer sk-456789" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role":"user","content":"你好"}],
    "stream": false
  }'
```

Anthropic 格式：

```bash
curl http://127.0.0.1:9898/v1/messages \
  -H "x-api-key: sk-456789" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role":"user","content":"你好"}],
    "stream": false
  }'
```

## 客户端接入

大多数支持自定义 API 地址的客户端都能用。配置方法：

| 配置项 | 本地部署 | HF Spaces |
|--------|---------|-----------|
| Base URL | `http://localhost:9898/v1` | `https://<用户名>-onyx.hf.space/v1` |
| API Key | 你设的 `CLIENT_API_KEY` 值 | 同左 |

Python 里用 `openai` 库的话：

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:9898/v1",
    api_key="sk-456789",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
```

## 支持的模型

内置了主流模型的映射，直接用模型名就行：

**Anthropic**
`claude-opus-4-6` · `claude-opus-4-5` · `claude-sonnet-4-6` · `claude-sonnet-4-5` · `claude-sonnet-4` · `claude-3-5-sonnet` · `claude-3-5-haiku` · `claude-3-opus` · `claude-haiku-4-5`

**OpenAI**
`gpt-4o` · `gpt-4o-mini` · `gpt-4-turbo` · `gpt-4` · `o1` · `o1-mini` · `o3-mini`

**Google**
`gemini-2.0-flash` · `gemini-2.5-pro`

不在列表里的模型也能用，传 Onyx 的原始格式 `Provider__api__model_version` 就行，比如 `OpenAI__api__gpt-4o`。找不到映射的模型名会默认当 Anthropic 处理。

## 环境变量

| 变量 | 说明 | 默认 |
|------|------|------|
| `ONYX_KEYS` | Onyx API Key，多个逗号分隔 | **必填** |
| `CLIENT_API_KEY` | 客户端鉴权密钥 | 空（不鉴权） |
| `CLIENT_API_KEYS` | 多个客户端密钥，逗号分隔，设了这个会忽略上面那个 | 空 |
| `PORT` | 监听端口 | `9898` |
| `LISTEN_ADDR` | 完整监听地址，比如 `0.0.0.0:8080`，设了会忽略 `PORT` | 空 |

请求体里还可以传一个 `persona_id`（整数），对应 Onyx 的 Persona，默认 `1`。

## 常见问题

**Q: Duplicate / Fork 了别人的项目，跑起来没反应？**

Secret 不会跟着代码走。你得自己去 Space Settings 里把 `ONYX_KEYS` 和 `CLIENT_API_KEY` 填上。

**Q: `/health` 返回的 `keys` 是 0？**

说明没读到 `ONYX_KEYS`。本地跑检查一下环境变量有没有传对，HF 上检查 Space Secrets 配了没。

**Q: 不设 `CLIENT_API_KEY` 行不行？**

能跑，但公网部署别这么干。没有鉴权谁都能调，你的 Onyx 配额会被白嫖光。

**Q: 流式响应断了 / 超时了？**

默认请求超时 5 分钟。如果模型响应特别长（比如深度研究），可能会超。另外检查一下中间有没有反向代理在限制连接时长。

**Q: 模型名写错了会怎样？**

不会报错，会被当成 Anthropic 模型透传给 Onyx。Onyx 那边认不认就看它了。