# 花椰菜 API Gateway

花椰菜是托管在 https://xshell.club 的 OpenAI 兼容大模型网关（实现基于 Sub2API 一类控制面）。面向开发者提供统一入口：对话、图像生成、视频生成，以及 embeddings / Anthropic messages / Gemini v1beta 形态。

## 一句话

把 OpenAI SDK 的 base_url 换成 https://xshell.club/v1，api_key 换成在控制台创建的密钥即可调用。

## 身份与联系

- 品牌：花椰菜
- 站点：https://xshell.club
- 控制台登录：https://xshell.club/login
- 注册：https://xshell.club/register（当前开放，邮箱后缀白名单含 @qq.com）
- 时区：Asia/Shanghai
- 站点内公开联系：微信 zhao13579shun（来自控制台 contact_info）

## Base URL

| 用途 | URL |
| --- | --- |
| 站点 / 控制台 | https://xshell.club |
| OpenAI 兼容 | https://xshell.club/v1 |
| Gemini 兼容探测 | https://xshell.club/v1beta |

## 鉴权

推理类接口需要 API Key。接受：

1. Authorization: Bearer <API_KEY>
2. x-api-key: <API_KEY>
3. x-goog-api-key: <API_KEY>

无密钥时网关返回 HTTP 401，JSON（过渡期同时带扁平 code 与 error.docs）：

{"code":"API_KEY_REQUIRED","message":"API key is required in Authorization header (Bearer scheme), x-api-key header, or x-goog-api-key header","error":{"type":"authentication_error","code":"API_KEY_REQUIRED","docs":"https://xshell.club/docs#authentication"}}

错误密钥返回：

{"code":"INVALID_API_KEY","message":"Invalid API key"}

Gemini 形态路径返回：

{"error":{"code":401,"message":"API key is required","status":"UNAUTHENTICATED"}}

## 已探测到的网关能力

下列路径在无密钥时由网关拦截（401），说明路由存在。完整模型名需持有效 Key 调用 GET /v1/models。

| 方法 | 路径 | 能力 |
| --- | --- | --- |
| POST | /v1/chat/completions | 对话补全 |
| POST | /v1/responses | OpenAI Responses |
| POST | /v1/images/generations | 图像生成 |
| POST | /v1/images/edits | 图像编辑 |
| POST | /v1/videos/generations | 视频生成 |
| POST | /v1/videos | 视频（别名） |
| POST | /v1/embeddings | 向量 |
| POST | /v1/messages | Anthropic Messages 形态 |
| GET | /v1/models | 模型列表（需 Key） |
| GET | /v1/realtime | 实时通道（需 Key） |
| GET/POST | /v1beta/models | Gemini 列表/调用形态 |

未挂路由（404）：GET/POST /v1/audio/speech。

仅支持 POST 的路径对 GET 返回 HTTP 405 + `Allow: POST, OPTIONS`（chat/completions、images/generations、images/edits、embeddings、messages）。`/v1/*` 与 `/v1beta/*` 的 OPTIONS 预检返回 204 及 CORS 头。

## 公开（无需 Key）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | /health | {"status":"ok","name":"花椰菜",...} 向后兼容 status |
| GET | /setup/status | 安装状态 |
| GET | /openapi.json | 本文件对应的机器描述（部署后） |
| GET | /llms.txt | 短索引 |
| GET | /faq | 常见问题（FAQPage） |
| GET | /api/v1/public/catalog | 能力目录 |

## OpenAI Python 示例

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-YOUR-KEY",
    base_url="https://xshell.club/v1",
)

chat = client.chat.completions.create(
    model="MODEL_ID",  # 以 GET /v1/models 为准
    messages=[{"role": "user", "content": "你好，花椰菜"}],
)
print(chat.choices[0].message.content)
```

## curl 示例

```bash
curl -sS https://xshell.club/v1/chat/completions \
  -H "Authorization: Bearer sk-YOUR-KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"ping"}]}'
```

## 控制台能力

- 用户 Key、用量、充值（payment_enabled=true）
- 可用渠道页（available_channels_enabled=true）
- 模型广场默认关闭（model_plaza_enabled=false）
- 无限画布：https://xshell.club/canvas-embed/
- 提示词动作库：https://xshell.club/prompt-lib/
- 登录后 Markdown：新手教程、生图教程

## 不要混淆

- 官方站点是 https://xshell.club。OpenAI SDK 的 base_url 是 https://xshell.club/v1。
- `/canvas-embed/` 是花椰菜无限画布（内嵌 infinite-canvas），`/prompt-lib/` 是提示词动作库。旧的 `/studio/` 已跳转到 `/canvas-embed/`。
- `/admin` 与 `/api/v1/admin/*` 是控制台，不是模型推理入口。

## 更新

本说明于 2026-10-13 将公开身份统一到 https://xshell.club。模型清单以持 Key 的 GET /v1/models 为准。