---
title: REST API 完整参考
description: 200+ 标准接口文档，覆盖用户、内容、AI、支付等全部模块。
category: api
order: 1
---

# REST API 完整参考

> 200+ 标准接口文档，覆盖用户、内容、AI、支付等全部模块。

## 📚 API 概览

**基础 URL：** `https://api.websopy.com/v1`

**认证方式：** Bearer Token

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.websopy.com/v1/user/profile
```

## 📋 端点列表

### 用户管理 `/user`

| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/user/profile` | 获取当前用户信息 |
| PUT | `/user/profile` | 更新用户信息 |
| GET | `/user/settings` | 获取用户设置 |
| PUT | `/user/settings` | 更新用户设置 |
| POST | `/user/avatar` | 上传头像 |

### 项目管理 `/projects`

| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/projects` | 列出项目 |
| POST | `/projects` | 创建项目 |
| GET | `/projects/:id` | 获取项目详情 |
| PUT | `/projects/:id` | 更新项目 |
| DELETE | `/projects/:id` | 删除项目 |
| GET | `/projects/:id/members` | 获取项目成员 |
| POST | `/projects/:id/members` | 添加成员 |

### 文件存储 `/storage`

| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/storage/files` | 列出文件 |
| POST | `/storage/upload` | 上传文件 |
| GET | `/storage/files/:id` | 获取文件信息 |
| DELETE | `/storage/files/:id` | 删除文件 |
| GET | `/storage/files/:id/download` | 下载文件 |

### AI 功能 `/ai`

| 方法 | 端点 | 说明 |
|------|------|------|
| POST | `/ai/chat` | 发送对话请求 |
| POST | `/ai/chat/stream` | 流式对话 |
| GET | `/ai/sessions` | 列出会话 |
| POST | `/ai/sessions` | 创建会话 |
| GET | `/ai/sessions/:id` | 获取会话详情 |
| DELETE | `/ai/sessions/:id` | 删除会话 |
| POST | `/ai/knowledge` | 创建知识库 |
| POST | `/ai/knowledge/:id/documents` | 添加文档 |

### 支付 `/payments`

| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/payments/orders` | 列出订单 |
| POST | `/payments/orders` | 创建订单 |
| GET | `/payments/orders/:id` | 订单详情 |
| POST | `/payments/checkout` | 创建结算会话 |
| GET | `/payments/subscriptions` | 订阅列表 |

## 🔍 请求与响应

### 请求头

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
X-Request-ID: unique-request-id
```

### 分页

```http
GET /projects?page=2&limit=20
```

响应包含分页信息：

```json
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 100,
    "total_pages": 5
  }
}
```

### 排序

```http
GET /projects?sort=created_at&order=desc
```

### 过滤

```http
GET /projects?status=active&category=ai
```

## 📝 错误处理

### 错误码

| 状态码 | 错误码 | 说明 |
|--------|--------|------|
| 400 | `INVALID_REQUEST` | 请求参数错误 |
| 401 | `UNAUTHORIZED` | 未认证或 Token 无效 |
| 403 | `FORBIDDEN` | 无权限访问 |
| 404 | `NOT_FOUND` | 资源不存在 |
| 429 | `RATE_LIMITED` | 请求过于频繁 |
| 500 | `SERVER_ERROR` | 服务器内部错误 |

### 错误响应格式

```json
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "参数 'name' 不能为空",
    "details": {
      "field": "name",
      "constraint": "required"
    }
  }
}
```

## 🔧 使用示例

### JavaScript/TypeScript

```typescript
const response = await fetch('https://api.websopy.com/v1/projects', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '我的项目',
    description: '项目描述'
  })
})

const data = await response.json()
console.log(data)
```

### Python

```python
import requests

response = requests.post(
    'https://api.websopy.com/v1/projects',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        'name': '我的项目',
        'description': '项目描述'
    }
)

data = response.json()
print(data)
```