MagicBook API

通用规范

请求格式、响应结构、认证方式。

请求格式

所有请求 Body 使用 application/json，响应也为 JSON。

统一响应结构

{
  "code": 200,
  "message": "success",
  "data": { ... }
}

字段	类型	说明
code	Integer	状态码，200 成功
message	String	提示信息
data	Any	响应数据，失败为 null

认证方式

除登录/注册外，所有接口需携带 JWT Token：

Authorization: Bearer <token>

Token 有效期 24 小时。

认证模块

用户注册与登录。

POST /api/auth/register

无需认证。

请求体

{
  "username": "xiaoming",
  "password": "123456",
  "nickname": "小明",
  "email": "xiaoming@example.com"
}

字段	类型	必填	说明
username	String	是	3-20 字符
password	String	是	6-50 字符
nickname	String	否	默认等于用户名
email	String	否	需符合格式

成功响应

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "username": "xiaoming",
    "nickname": "小明",
    "avatar": null,
    "status": 0,
    "email": "xiaoming@example.com",
    "createTime": "2026-03-30T09:00:00"
  }
}

失败响应

code	message	原因
400	用户名已存在	用户名重复
400	邮箱已被注册	邮箱重复

POST /api/auth/login

无需认证。

请求体

{
  "username": "xiaoming",
  "password": "123456"
}

成功响应

{
  "code": 200,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1...",
    "tokenType": "Bearer",
    "expiresIn": 86400,
    "userId": 1,
    "username": "xiaoming"
  }
}

失败响应

code	message	原因
401	用户名或密码错误	用户不存在或密码错误
403	账号已被禁用	用户状态为禁用

用户中心

用户信息管理。

GET /api/user/info

获取当前登录用户的详细信息。

成功响应

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "username": "xiaoming",
    "nickname": "小明",
    "avatar": "https://example.com/avatar.jpg",
    "status": 0,
    "email": "xiaoming@example.com",
    "createTime": "2026-03-30T09:00:00"
  }
}

错误码说明

全局错误码及其含义。

code	含义
200	成功
400	请求参数错误
401	未认证（Token 缺失或过期）
403	无权限
404	资源不存在
500	服务器内部错误

数据结构参考

接口中使用的核心数据模型。

UserVO（用户信息）

字段	类型	说明
id	Long	用户 ID
username	String	用户名
nickname	String	昵称
avatar	String	头像 URL
status	Integer	0 正常 / 1 禁用
email	String	邮箱
createTime	DateTime	注册时间

StoryBook（故事书）

字段	类型	说明
id	Long	故事书 ID
userId	Long	所属用户 ID
title	String	故事标题
prompt	String	提示词
style	String	文章风格
ageGroup	String	目标年龄段
imageStyle	String	画面风格
language	String	故事语言
pageCount	Integer	页数
coverImageUrl	String	封面图片 URL
status	Integer	0 生成中 / 1 已完成 / 2 失败
createTime	DateTime	创建时间
updateTime	DateTime	最后更新时间