gongxiangp2/yedir/docs/API.md

# API 文档

本文档详细说明了图片背景处理工具的API端点。

## 基础URL

所有API请求的基础URL为：

```
http://localhost:3000/api
```

在生产环境中，请替换为实际的域名。

## 认证

除了登录和注册API外，所有API请求都需要认证。通过在HTTP请求头中添加JWT令牌进行认证：

```
Authorization: Bearer <your_token>
```

### 获取令牌

#### 用户注册

```
POST /auth/register
```

**请求参数：**

| 参数名     | 类型     | 必需 | 描述       |
|------------|----------|------|------------|
| username   | string   | 是   | 用户名     |
| email      | string   | 是   | 电子邮箱   |
| password   | string   | 是   | 密码       |

**响应示例：**

```json
{
  "success": true,
  "message": "用户注册成功",
  "data": {
    "id": "6107f2daef964c001c384a12",
    "username": "user1",
    "email": "user1@example.com"
  }
}
```

#### 用户登录

```
POST /auth/login
```

**请求参数：**

| 参数名     | 类型     | 必需 | 描述       |
|------------|----------|------|------------|
| email      | string   | 是   | 电子邮箱   |
| password   | string   | 是   | 密码       |

**响应示例：**

```json
{
  "success": true,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "6107f2daef964c001c384a12",
      "username": "user1",
      "email": "user1@example.com",
      "role": "user",
      "credits": 10
    }
  }
}
```

#### 忘记密码

```
POST /auth/forgot-password
```

**请求参数：**

| 参数名     | 类型     | 必需 | 描述       |
|------------|----------|------|------------|
| email      | string   | 是   | 电子邮箱   |

**响应示例：**

```json
{
  "success": true,
  "message": "密码重置链接已发送到您的邮箱"
}
```

#### 重置密码

```
POST /auth/reset-password
```

**请求参数：**

| 参数名     | 类型     | 必需 | 描述         |
|------------|----------|------|--------------|
| token      | string   | 是   | 重置令牌     |
| password   | string   | 是   | 新密码       |

**响应示例：**

```json
{
  "success": true,
  "message": "密码重置成功"
}
```

## 用户管理

### 获取用户资料

```
GET /users/profile
```

**响应示例：**

```json
{
  "success": true,
  "data": {
    "id": "6107f2daef964c001c384a12",
    "username": "user1",
    "email": "user1@example.com",
    "role": "user",
    "credits": 10,
    "createdAt": "2023-01-15T08:25:30.123Z"
  }
}
```

### 更新用户资料

```
PUT /users/profile
```

**请求参数：**

| 参数名     | 类型     | 必需 | 描述       |
|------------|----------|------|------------|
| username   | string   | 否   | 用户名     |
| email      | string   | 否   | 电子邮箱   |

**响应示例：**

```json
{
  "success": true,
  "message": "资料更新成功",
  "data": {
    "id": "6107f2daef964c001c384a12",
    "username": "user1_updated",
    "email": "user1@example.com"
  }
}
```

### 修改密码

```
PUT /users/password
```

**请求参数：**

| 参数名         | 类型     | 必需 | 描述       |
|----------------|----------|------|------------|
| currentPassword| string   | 是   | 当前密码   |
| newPassword    | string   | 是   | 新密码     |

**响应示例：**

```json
{
  "success": true,
  "message": "密码修改成功"
}
```

## 图像处理

### 上传图片

```
POST /images/upload
```

**请求参数：**

| 参数名     | 类型     | 必需 | 描述       |
|------------|----------|------|------------|
| file       | file     | 是   | 图片文件   |

**响应示例：**

```json
{
  "success": true,
  "data": {
    "fileId": "image_12345",
    "fileName": "upload.jpg",
    "fileUrl": "https://minio-server/xiaogongju/image_12345.jpg",
    "filePath": "/uploads/image_12345.jpg",
    "fileSize": 102400,
    "mimeType": "image/jpeg"
  }
}
```

### 移除背景

```
POST /images/remove-bg
```

**请求参数：**

| 参数名     | 类型     | 必需 | 描述                |
|------------|----------|------|---------------------|
| imageId    | string   | 否   | 已上传图片的ID      |
| imageUrl   | string   | 否   | 或直接提供图片URL   |
| size       | string   | 否   | 输出尺寸            |
| type       | string   | 否   | 前景类型(auto/人物/产品)|

**响应示例：**

```json
{
  "success": true,
  "data": {
    "resultId": "result_12345",
    "resultUrl": "https://minio-server/xiaogongju/result_12345.png",
    "credits": 1
  }
}
```

### 生成背景

```
POST /images/generate-bg
```

**请求参数：**

| 参数名     | 类型     | 必需 | 描述                    |
|------------|----------|------|-----------------------|
| imageId    | string   | 是   | 已上传图片的ID(透明背景)|
| prompt     | string   | 是   | 背景生成提示词         |
| style      | string   | 否   | 背景风格               |

**响应示例：**

```json
{
  "success": true,
  "data": {
    "resultId": "result_12346",
    "resultUrl": "https://minio-server/xiaogongju/result_12346.jpg",
    "credits": 2
  }
}
```

### 图像重绘

```
POST /images/repaint
```

**请求参数：**

| 参数名     | 类型     | 必需 | 描述                |
|------------|----------|------|---------------------|
| imageId    | string   | 是   | 已上传图片的ID      |
| prompt     | string   | 是   | 重绘提示词          |
| strength   | number   | 否   | 重绘强度(0.0-1.0)   |

**响应示例：**

```json
{
  "success": true,
  "data": {
    "resultId": "result_12347",
    "resultUrl": "https://minio-server/xiaogongju/result_12347.jpg",
    "credits": 3
  }
}
```

### 海报生成

```
POST /images/poster
```

**请求参数：**

| 参数名     | 类型     | 必需 | 描述                |
|------------|----------|------|---------------------|
| prompt     | string   | 是   | 海报生成提示词      |
| style      | string   | 否   | 海报风格            |
| ratio      | string   | 否   | 尺寸比例(16:9/4:3/1:1)|

**响应示例：**

```json
{
  "success": true,
  "data": {
    "resultId": "result_12348",
    "resultUrl": "https://minio-server/xiaogongju/result_12348.jpg",
    "credits": 5
  }
}
```

## 积分管理

### 获取积分信息

```
GET /credits
```

**响应示例：**

```json
{
  "success": true,
  "data": {
    "credits": 10,
    "usedCredits": 5,
    "transactions": [
      {
        "id": "trans_12345",
        "type": "purchase",
        "amount": 10,
        "date": "2023-02-01T10:20:30.123Z"
      },
      {
        "id": "trans_12346",
        "type": "usage",
        "amount": -5,
        "operation": "remove-bg",
        "date": "2023-02-02T15:30:45.678Z"
      }
    ]
  }
}
```

### 购买积分

```
POST /credits/purchase
```

**请求参数：**

| 参数名     | 类型     | 必需 | 描述           |
|------------|----------|------|----------------|
| amount     | number   | 是   | 购买积分数量   |
| paymentMethod| string | 是   | 支付方式       |

**响应示例：**

```json
{
  "success": true,
  "message": "积分购买成功",
  "data": {
    "transactionId": "trans_12347",
    "credits": 20,
    "amount": "¥50.00",
    "paymentMethod": "alipay",
    "date": "2023-02-05T09:15:22.345Z"
  }
}
```

## 错误码

| 错误码 | 描述                      |
|--------|---------------------------|
| 400    | 请求参数错误              |
| 401    | 未授权或令牌无效          |
| 403    | 权限不足                  |
| 404    | 资源不存在                |
| 422    | 参数验证失败              |
| 429    | 请求频率超限              |
| 500    | 服务器内部错误            |

## 错误响应示例

```json
{
  "success": false,
  "message": "请求参数错误",
  "error": {
    "code": 400,
    "details": "缺少必要参数: prompt"
  }
}
```