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	是	密码

响应示例：

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

用户登录

POST /auth/login

请求参数：

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

响应示例：

{
  "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	是	电子邮箱

响应示例：

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

重置密码

POST /auth/reset-password

请求参数：

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

响应示例：

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

用户管理

获取用户资料

GET /users/profile

响应示例：

{
  "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	否	电子邮箱

响应示例：

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

修改密码

PUT /users/password

请求参数：

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

响应示例：

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

图像处理

上传图片

POST /images/upload

请求参数：

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

响应示例：

{
  "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/人物/产品)

响应示例：

{
  "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	否	背景风格

响应示例：

{
  "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)

响应示例：

{
  "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)

响应示例：

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

积分管理

获取积分信息

GET /credits

响应示例：

{
  "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	是	支付方式

响应示例：

{
  "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	服务器内部错误

错误响应示例

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