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,175 @@
|
||||
::: info
|
||||
This English version is translated by **Gemini 3 Flash**.
|
||||
:::
|
||||
|
||||
# Chat Completions
|
||||
|
||||
The chat generation interface, compatible with the OpenAI Chat Completions API.
|
||||
|
||||
## Endpoint
|
||||
|
||||
```
|
||||
POST /v1/chat/completions
|
||||
```
|
||||
|
||||
## Request Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `model` | string | ✅ | Model name |
|
||||
| `messages` | array | ✅ | List of messages |
|
||||
| `stream` | boolean | ❌ | Whether to enable streaming responses (recommended) |
|
||||
|
||||
### messages Format
|
||||
|
||||
```json
|
||||
{
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": "Generate a cute cat"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Multi-modal Requests (Image-to-Image / Image-to-Text)
|
||||
|
||||
```json
|
||||
{
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Make this image more vibrant"
|
||||
},
|
||||
{
|
||||
"type": "image_url",
|
||||
"image_url": {
|
||||
"url": "data:image/jpeg;base64,/9j/4AAQ..."
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Image Limitations
|
||||
|
||||
| Item | Description |
|
||||
| --- | --- |
|
||||
| Supported Formats | PNG, JPEG, GIF, WebP |
|
||||
| Quantity Limit | Default 5, Maximum 10 |
|
||||
| Data Format | Base64 Data URL (`data:image/jpeg;base64,...`) |
|
||||
| Auto-transformation | The server automatically converts images to JPG format |
|
||||
|
||||
## Non-streaming Response
|
||||
|
||||
### Request Example
|
||||
|
||||
```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"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
### Response Example
|
||||
|
||||
```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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Streaming Response
|
||||
|
||||
::: tip Recommendation
|
||||
Streaming mode includes a heartbeat mechanism to keep the connection alive, preventing timeouts during long generations.
|
||||
:::
|
||||
|
||||
### Request Example
|
||||
|
||||
```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"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
### Response Example
|
||||
|
||||
```
|
||||
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]
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Queue Full (429)
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"message": "Queue is full",
|
||||
"type": "rate_limit_exceeded",
|
||||
"code": "QUEUE_FULL"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: tip Solution
|
||||
Enabling streaming mode (`stream: true`) allows for unlimited queuing, avoiding 429 errors.
|
||||
:::
|
||||
|
||||
### Model Not Supported (400)
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"message": "No Worker supports model: invalid-model",
|
||||
"type": "invalid_request_error",
|
||||
"code": "MODEL_NOT_FOUND"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,74 @@
|
||||
::: info
|
||||
This English version is translated by **Gemini 3 Flash**.
|
||||
:::
|
||||
|
||||
# Cookies API
|
||||
|
||||
Retrieve cookies from browser instances, which can be used by other tools.
|
||||
|
||||
## Endpoint
|
||||
|
||||
```
|
||||
GET /v1/cookies
|
||||
```
|
||||
|
||||
## Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `name` | string | ❌ | Browser instance name |
|
||||
| `domain` | string | ❌ | Filter cookies by a specific domain |
|
||||
|
||||
## Request Example
|
||||
|
||||
### Get All Cookies
|
||||
|
||||
```bash
|
||||
curl -X GET http://localhost:3000/v1/cookies \
|
||||
-H "Authorization: Bearer sk-your-key"
|
||||
```
|
||||
|
||||
### Specify Instance and Domain
|
||||
|
||||
```bash
|
||||
curl -X GET "http://localhost:3000/v1/cookies?name=browser_default&domain=lmarena.ai" \
|
||||
-H "Authorization: Bearer sk-your-key"
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
```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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Scenarios
|
||||
|
||||
::: tip Application Scenarios
|
||||
- Export cookies for use in other automation tools.
|
||||
- Leverage this project's automatic session renewal to keep cookies fresh.
|
||||
- Debug login state issues.
|
||||
:::
|
||||
@@ -0,0 +1,82 @@
|
||||
::: info
|
||||
This English version is translated by **Gemini 3 Flash**.
|
||||
:::
|
||||
|
||||
# Models API
|
||||
|
||||
Retrieve the list of currently available models.
|
||||
|
||||
## Endpoint
|
||||
|
||||
```
|
||||
GET /v1/models
|
||||
```
|
||||
|
||||
## Request Example
|
||||
|
||||
```bash
|
||||
curl -X GET http://localhost:3000/v1/models \
|
||||
-H "Authorization: Bearer sk-your-key"
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
```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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Model Naming Conventions
|
||||
|
||||
### Short Form
|
||||
|
||||
Use the Model ID directly:
|
||||
|
||||
```
|
||||
gemini-3-pro-image-preview
|
||||
```
|
||||
|
||||
The system will automatically match a Worker that supports this model.
|
||||
|
||||
### Explicit Backend Form
|
||||
|
||||
Use the `backend/model` format:
|
||||
|
||||
```
|
||||
lmarena/gemini-3-pro-image-preview
|
||||
gemini_biz/gemini-3-pro-image-preview
|
||||
```
|
||||
|
||||
This forces the request to be handled by a specific backend.
|
||||
|
||||
## Model Types
|
||||
|
||||
| Type | Description |
|
||||
| --- | --- |
|
||||
| `image` | Image generation models |
|
||||
| `text` | Text generation models |
|
||||
|
||||
::: info Note
|
||||
The list of returned models depends on the currently configured Workers and their adapter types.
|
||||
:::
|
||||
@@ -0,0 +1,78 @@
|
||||
::: info
|
||||
This English version is translated by **Gemini 3 Flash**.
|
||||
:::
|
||||
|
||||
# API Overview
|
||||
|
||||
WebAI2API provides a RESTful API compatible with the OpenAI format.
|
||||
|
||||
## Basic Information
|
||||
|
||||
- **Base URL**: `http://localhost:3000`
|
||||
- **Authentication**: Bearer Token
|
||||
|
||||
### Request Headers
|
||||
|
||||
```http
|
||||
Authorization: Bearer sk-your-secret-key
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## API Endpoints List
|
||||
|
||||
### OpenAI Compatible Interfaces
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
| --- | --- | --- |
|
||||
| POST | `/v1/chat/completions` | Chat Generation |
|
||||
| GET | `/v1/models` | Retrieve Model List |
|
||||
| GET | `/v1/cookies` | Retrieve Cookies |
|
||||
|
||||
## Error Responses
|
||||
|
||||
All API errors return a consistent format:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"message": "Error description",
|
||||
"type": "error_type",
|
||||
"code": "ERROR_CODE"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Common Error Codes
|
||||
|
||||
| HTTP Status | Error Type | Description |
|
||||
| --- | --- | --- |
|
||||
| 401 | `unauthorized` | Authentication failed |
|
||||
| 400 | `invalid_request` | Invalid request parameters |
|
||||
| 404 | `not_found` | Resource not found |
|
||||
| 429 | `rate_limit` | Too many requests |
|
||||
| 500 | `internal_error` | Internal server error |
|
||||
| 503 | `service_unavailable` | Service unavailable |
|
||||
|
||||
## Streaming Responses
|
||||
|
||||
For requests with `stream: true`, the response uses the Server-Sent Events (SSE) format:
|
||||
|
||||
```
|
||||
data: {"id":"...","object":"chat.completion.chunk",...}
|
||||
|
||||
: keep-alive
|
||||
|
||||
data: {"id":"...","object":"chat.completion.chunk",...}
|
||||
|
||||
data: [DONE]
|
||||
```
|
||||
|
||||
::: tip Heartbeat/Keep-alive
|
||||
Streaming requests automatically send heartbeat packets to prevent connection timeouts. The format depends on the configured `keepalive.mode`.
|
||||
:::
|
||||
|
||||
## Related Documents
|
||||
|
||||
- [Chat Completions](/en/api/chat) - Detailed documentation for the chat generation interface.
|
||||
- [Models](/en/api/models) - Model list interface.
|
||||
- [Cookies](/en/api/cookies) - Cookie retrieval interface.
|
||||
Reference in New Issue
Block a user