# API 文档 本文档详细说明了图片背景处理工具的API端点。 ## 基础URL 所有API请求的基础URL为： ``` http://localhost:3000/api ``` 在生产环境中，请替换为实际的域名。 ## 认证 除了登录和注册API外，所有API请求都需要认证。通过在HTTP请求头中添加JWT令牌进行认证： ``` Authorization: Bearer ``` ### 获取令牌 #### 用户注册 ``` 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" } } ```