mirror of
https://github.com/foxhui/WebAI2API.git
synced 2026-06-16 21:03:59 +08:00
docs: 移除代码文件，初始化文档专用分支
This commit is contained in:
foxhui
@@ -0,0 +1,171 @@
|
||||
# Chat Completions
|
||||
|
||||
对话生成接口，兼容 OpenAI Chat Completions API。
|
||||
|
||||
## 端点
|
||||
|
||||
```
|
||||
POST /v1/chat/completions
|
||||
```
|
||||
|
||||
## 请求参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `model` | string | ✅ | 模型名称 |
|
||||
| `messages` | array | ✅ | 消息列表 |
|
||||
| `stream` | boolean | ❌ | 是否启用流式响应（推荐开启） |
|
||||
|
||||
### messages 格式
|
||||
|
||||
```json
|
||||
{
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": "生成一只可爱的猫"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 多模态请求（图生图）
|
||||
|
||||
```json
|
||||
{
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "让这张图片更加鲜艳"
|
||||
},
|
||||
{
|
||||
"type": "image_url",
|
||||
"image_url": {
|
||||
"url": "data:image/jpeg;base64,/9j/4AAQ..."
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 图片限制
|
||||
|
||||
| 限制项 | 说明 |
|
||||
| --- | --- |
|
||||
| 支持格式 | PNG, JPEG, GIF, WebP |
|
||||
| 数量限制 | 默认 5 张，最大 10 张 |
|
||||
| 数据格式 | Base64 Data URL (`data:image/jpeg;base64,...`) |
|
||||
| 自动转换 | 服务器会自动转换为 JPG 格式 |
|
||||
|
||||
## 非流式响应
|
||||
|
||||
### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/v1/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer sk-your-key" \
|
||||
-d '{
|
||||
"model": "gemini-3-pro-image-preview",
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": "generate a cat"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "chatcmpl-1732374740123",
|
||||
"object": "chat.completion",
|
||||
"created": 1732374740,
|
||||
"model": "gemini-3-pro-image-preview",
|
||||
"choices": [
|
||||
{
|
||||
"index": 0,
|
||||
"message": {
|
||||
"role": "assistant",
|
||||
"content": ""
|
||||
},
|
||||
"finish_reason": "stop"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 流式响应
|
||||
|
||||
::: tip 推荐使用
|
||||
流式模式包含心跳保活机制，可以避免长时间生成导致的连接超时。
|
||||
:::
|
||||
|
||||
### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/v1/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer sk-your-key" \
|
||||
-d '{
|
||||
"model": "gemini-3-pro-image-preview",
|
||||
"stream": true,
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": "generate a cat"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
```
|
||||
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1732374740,"model":"gemini-3-pro-image-preview","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
|
||||
|
||||
: keep-alive
|
||||
|
||||
: keep-alive
|
||||
|
||||
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1732374740,"model":"gemini-3-pro-image-preview","choices":[{"index":0,"delta":{"content":""},"finish_reason":"stop"}]}
|
||||
|
||||
data: [DONE]
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 队列已满 (429)
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"message": "队列已满",
|
||||
"type": "rate_limit_exceeded",
|
||||
"code": "QUEUE_FULL"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: tip 解决方案
|
||||
启用流式模式 (`stream: true`) 可以无限排队，避免 429 错误。
|
||||
:::
|
||||
|
||||
### 模型不支持 (400)
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"message": "没有 Worker 支持模型: invalid-model",
|
||||
"type": "invalid_request_error",
|
||||
"code": "MODEL_NOT_FOUND"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,70 @@
|
||||
# Cookies API
|
||||
|
||||
获取浏览器实例的 Cookie，可用于其他工具。
|
||||
|
||||
## 端点
|
||||
|
||||
```
|
||||
GET /v1/cookies
|
||||
```
|
||||
|
||||
## 查询参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `name` | string | ❌ | 浏览器实例名称 |
|
||||
| `domain` | string | ❌ | 过滤指定域名的 Cookie |
|
||||
|
||||
## 请求示例
|
||||
|
||||
### 获取所有 Cookie
|
||||
|
||||
```bash
|
||||
curl -X GET http://localhost:3000/v1/cookies \
|
||||
-H "Authorization: Bearer sk-your-key"
|
||||
```
|
||||
|
||||
### 指定实例和域名
|
||||
|
||||
```bash
|
||||
curl -X GET "http://localhost:3000/v1/cookies?name=browser_default&domain=lmarena.ai" \
|
||||
-H "Authorization: Bearer sk-your-key"
|
||||
```
|
||||
|
||||
## 响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"instance": "browser_default",
|
||||
"cookies": [
|
||||
{
|
||||
"name": "_GRECAPTCHA",
|
||||
"value": "09ADxxxxxx",
|
||||
"domain": "www.google.com",
|
||||
"path": "/recaptcha",
|
||||
"expires": 1780000000,
|
||||
"httpOnly": true,
|
||||
"secure": true,
|
||||
"sameSite": "None"
|
||||
},
|
||||
{
|
||||
"name": "OTZ",
|
||||
"value": "8888888_24_24__24_",
|
||||
"domain": "accounts.google.com",
|
||||
"path": "/",
|
||||
"expires": 1760000000,
|
||||
"httpOnly": false,
|
||||
"secure": true,
|
||||
"sameSite": "None"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 使用场景
|
||||
|
||||
::: tip 应用场景
|
||||
- 将 Cookie 导出给其他自动化工具使用
|
||||
- 利用本项目的自动续登功能保持 Cookie 新鲜
|
||||
- 调试登录状态问题
|
||||
:::
|
||||
@@ -0,0 +1,78 @@
|
||||
# Models API
|
||||
|
||||
获取当前可用的模型列表。
|
||||
|
||||
## 端点
|
||||
|
||||
```
|
||||
GET /v1/models
|
||||
```
|
||||
|
||||
## 请求示例
|
||||
|
||||
```bash
|
||||
curl -X GET http://localhost:3000/v1/models \
|
||||
-H "Authorization: Bearer sk-your-key"
|
||||
```
|
||||
|
||||
## 响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"object": "list",
|
||||
"data": [
|
||||
{
|
||||
"id": "gemini-3-pro-image-preview",
|
||||
"object": "model",
|
||||
"created": 1732456789,
|
||||
"owned_by": "internal_server"
|
||||
},
|
||||
{
|
||||
"id": "lmarena/gemini-3-pro-image-preview",
|
||||
"object": "model",
|
||||
"created": 1732456789,
|
||||
"owned_by": "lmarena"
|
||||
},
|
||||
{
|
||||
"id": "seedream-4-high-res-fal",
|
||||
"object": "model",
|
||||
"created": 1732456789,
|
||||
"owned_by": "internal_server"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 模型命名规则
|
||||
|
||||
### 简写形式
|
||||
|
||||
直接使用模型 ID：
|
||||
|
||||
```
|
||||
gemini-3-pro-image-preview
|
||||
```
|
||||
|
||||
系统会自动匹配到支持该模型的 Worker。
|
||||
|
||||
### 指定后端形式
|
||||
|
||||
使用 `backend/model` 格式：
|
||||
|
||||
```
|
||||
lmarena/gemini-3-pro-image-preview
|
||||
gemini_biz/gemini-3-pro-image-preview
|
||||
```
|
||||
|
||||
强制使用指定后端处理请求。
|
||||
|
||||
## 模型类型
|
||||
|
||||
| 类型 | 说明 |
|
||||
| --- | --- |
|
||||
| `image` | 图片生成模型 |
|
||||
| `text` | 文本生成模型 |
|
||||
|
||||
::: info 说明
|
||||
返回的模型列表取决于当前配置的 Worker 和适配器类型。
|
||||
:::
|
||||
@@ -0,0 +1,86 @@
|
||||
# API 概览
|
||||
|
||||
WebAI2API 提供兼容 OpenAI 格式的 RESTful API。
|
||||
|
||||
## 基础信息
|
||||
|
||||
- **Base URL**: `http://localhost:3000`
|
||||
- **认证方式**: Bearer Token
|
||||
|
||||
### 请求头
|
||||
|
||||
```http
|
||||
Authorization: Bearer sk-your-secret-key
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## API 端点列表
|
||||
|
||||
### OpenAI 兼容接口
|
||||
|
||||
| 方法 | 端点 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| POST | `/v1/chat/completions` | 对话生成 |
|
||||
| GET | `/v1/models` | 获取模型列表 |
|
||||
| GET | `/v1/cookies` | 获取 Cookie |
|
||||
|
||||
### 管理接口
|
||||
|
||||
| 方法 | 端点 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| GET | `/admin/status` | 服务状态 |
|
||||
| GET | `/admin/stats` | 统计信息 |
|
||||
| GET | `/admin/queue` | 队列状态 |
|
||||
| POST | `/admin/restart` | 重启服务 |
|
||||
| POST | `/admin/stop` | 停止服务 |
|
||||
| GET | `/admin/vnc/status` | VNC 状态 |
|
||||
| POST | `/admin/cache/clear` | 清理缓存 |
|
||||
|
||||
## 错误响应
|
||||
|
||||
所有 API 错误返回统一格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"message": "错误描述",
|
||||
"type": "error_type",
|
||||
"code": "ERROR_CODE"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 常见错误码
|
||||
|
||||
| HTTP 状态码 | 错误类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| 401 | `unauthorized` | 认证失败 |
|
||||
| 400 | `invalid_request` | 请求参数错误 |
|
||||
| 404 | `not_found` | 资源不存在 |
|
||||
| 429 | `rate_limit` | 请求过多 |
|
||||
| 500 | `internal_error` | 服务器内部错误 |
|
||||
| 503 | `service_unavailable` | 服务不可用 |
|
||||
|
||||
## 流式响应
|
||||
|
||||
对于 `stream: true` 的请求，响应使用 Server-Sent Events (SSE) 格式：
|
||||
|
||||
```
|
||||
data: {"id":"...","object":"chat.completion.chunk",...}
|
||||
|
||||
: keep-alive
|
||||
|
||||
data: {"id":"...","object":"chat.completion.chunk",...}
|
||||
|
||||
data: [DONE]
|
||||
```
|
||||
|
||||
::: tip 心跳保活
|
||||
流式请求会自动发送心跳包防止连接超时，格式取决于配置的 `keepalive.mode`。
|
||||
:::
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Chat Completions](/api/chat) - 对话生成接口详解
|
||||
- [Models](/api/models) - 模型列表接口
|
||||
- [Cookies](/api/cookies) - Cookie 获取接口
|
||||
Reference in New Issue
Block a user