可乐画图 - API文档

本文档详细描述了可乐画图项目的API接口设计，供前端开发团队进行接口对接。

API版本信息：

当前API版本：v1

状态：已实现的接口

  • POST /v1/user/login - 用户登录
  • GET /v1/styles - 获取风格列表
  • POST /v1/images/process - 上传图片并选择风格进行处理

1. 接口概述

本项目API接口分为两大类：

  1. 小程序前端接口：供微信小程序调用的接口
  2. 管理后台接口：供管理员使用的后台管理接口

接口基本信息：

2. 小程序前端接口

2.1 用户认证

POST /v1/user/login

用户通过微信登录，获取用户身份

请求参数：

参数名 类型 必填 描述
code string 是 微信登录临时凭证
userInfo object 否 用户基本信息

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "token": "用户身份令牌",
    "userId": "用户ID",
    "isNewUser": true
  }
}

2.2 风格相关接口

GET /v1/styles

获取可用的风格列表，用于风格广场展示

请求参数：

参数名 类型 必填 描述
page number 否 页码，默认为1
limit number 否 每页条数，默认为20

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 100,
    "list": [
      {
        "styleId": "风格ID",
        "name": "风格名称",
        "previewImage": "预览图URL",
        "description": "风格描述"
      }
    ]
  }
}

2.3 图片处理接口

POST /v1/images/process

上传图片并选择风格进行处理

请求参数：

参数名 类型 必填 描述
styleId string 是 风格ID
image file 是 图片文件
width number 否 期望输出宽度，默认512
height number 否 期望输出高度，默认512

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "处理任务ID",
    "status": "pending",
    "estimatedTime": 10
  }
}

2.4 任务相关接口

GET /v1/tasks

获取用户的处理任务列表

请求参数：

参数名 类型 必填 描述
page number 否 页码，默认为1
limit number 否 每页条数，默认为20
status string 否 任务状态(all/pending/success/failed)，默认all

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 50,
    "list": [
      {
        "taskId": "任务ID",
        "styleId": "风格ID",
        "styleName": "风格名称",
        "status": "任务状态",
        "createdAt": "创建时间",
        "completedAt": "完成时间",
        "resultImage": "结果图片URL",
        "originalImage": "原始图片URL"
      }
    ]
  }
}
GET /v1/tasks/{taskId}

获取单个任务的详细信息

请求参数：

无

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "任务ID",
    "styleId": "风格ID",
    "styleName": "风格名称",
    "styleDescription": "风格描述",
    "status": "任务状态",
    "createdAt": "创建时间",
    "completedAt": "完成时间",
    "resultImage": "结果图片URL",
    "originalImage": "原始图片URL",
    "width": 512,
    "height": 512
  }
}

3. 管理后台接口

3.1 管理员认证

POST /v1/admin/login

管理员登录系统

请求参数：

参数名 类型 必填 描述
username string 是 管理员用户名
password string 是 管理员密码

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "token": "JWT令牌",
    "expiresIn": 86400
  }
}

3.2 风格管理接口

GET /v1/admin/styles

获取所有风格列表(包括停用的)

请求参数：

参数名 类型 必填 描述
page number 否 页码，默认为1
limit number 否 每页条数，默认为20
status string 否 状态(all/enabled/disabled)，默认all

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 100,
    "list": [
      {
        "styleId": "风格ID",
        "name": "风格名称",
        "description": "风格描述",
        "previewImage": "预览图URL",
        "prompt": "提示词",
        "status": "启用状态",
        "createdAt": "创建时间"
      }
    ]
  }
}
POST /v1/admin/styles

添加新的风格

请求参数：

参数名 类型 必填 描述
name string 是 风格名称
description string 是 风格描述
prompt string 是 提示词
previewImage file 是 预览图片
status string 否 状态(enabled/disabled)，默认enabled

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "styleId": "新创建的风格ID"
  }
}
PUT /v1/admin/styles/{styleId}

编辑已有风格

请求参数：

参数名 类型 必填 描述
name string 否 风格名称
description string 否 风格描述
prompt string 否 提示词
previewImage file 否 预览图片
status string 否 状态(enabled/disabled)

响应示例：

{
  "code": 0,
  "message": "success",
  "data": null
}
DELETE /v1/admin/styles/{styleId}

删除风格

请求参数：

无

响应示例：

{
  "code": 0,
  "message": "success",
  "data": null
}

4. 错误码说明

错误码 说明
0 成功
10001 参数错误
10002 用户未登录
10003 权限不足
20001 风格不存在
20002 风格已停用
30001 图片上传失败
30002 图片格式不支持
30003 图片尺寸超限
40001 任务不存在
40002 任务处理失败
50001 系统内部错误
返回首页