RenderPSD API 文档

本文档列出了 RenderPSD 平台用户端的所有 API 接口，您可以基于这些接口自行开发对接程序。

基础信息

Base URL {您的域名}/api
请求格式 JSON（Content-Type: application/json）
字符编码 UTF-8

鉴权方式

除登录/注册外，所有接口均需在请求头中携带 JWT Token：

Authorization: Bearer <your_token>

Token 通过 登录/注册 接口获取，有效期内可复用。Token 过期后需重新登录获取。

未携带 Token 或 Token 无效时，返回 code: "UNAUTHORIZED"。

统一响应格式

所有接口返回统一 JSON 结构：

{
  "success": true,        // 是否成功
  "message": "OK",        // 提示信息
  "data": { ... }         // 业务数据，失败时为 null
}

分页接口的 data 结构：

{
  "total": 100,           // 总记录数
  "current": 1,           // 当前页码
  "pageSize": 20,         // 每页条数
  "list": [ ... ]         // 数据列表
}

用户接口

POST /user/sendVerifyCode

发送短信验证码到指定手机号，用于登录/注册。（无需鉴权）

请求参数

字段 类型 必填 说明
mobile string 是 11位手机号

请求示例

POST /api/user/sendVerifyCode
Content-Type: application/json

{
  "mobile": "13800138000"
}

响应示例

{
  "success": true,
  "message": "OK",
  "data": {
    "verifyToken": "eyJ..."   // 验证Token，登录时需要传回
  }
}
POST /user/signup

手机号 + 验证码 登录或注册。首次使用自动注册并赠送初始额度。（无需鉴权）

请求参数

字段 类型 必填 说明
mobile string 是 11位手机号
verifyCode string 是 6位短信验证码
verifyToken string 是 发送验证码时返回的Token

请求示例

POST /api/user/signup
Content-Type: application/json

{
  "mobile": "13800138000",
  "verifyCode": "123456",
  "verifyToken": "eyJ..."
}

响应示例

{
  "success": true,
  "message": "OK",
  "data": {
    "token": "eyJ...",                    // JWT Token，后续请求需携带
    "expiredTime": "2026-03-19 12:00:00"  // Token过期时间
  }
}
GET /user/profile

获取当前登录用户的基本信息和剩余额度。

响应示例

{
  "success": true,
  "message": "OK",
  "data": {
    "id": 1,
    "mobile": "13800138000",
    "isAdmin": "n",
    "psdUsed": 5,              // 已用PSD上传次数
    "renderUsed": 20,          // 已用渲染次数
    "psdAvailable": 10,        // 可用PSD上传次数
    "renderAvailable": 80,     // 可用渲染次数
    "apiToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",  // API访问Token
    "apiTokenExpiredAt": "2026-03-26 10:00:00",        // Token过期时间
    "createdAt": "2026-03-01 10:00:00"
  }
}

PSD 接口

POST /psd/create

创建一条PSD记录。需先通过 上传凭证 将PSD文件上传至OSS，再将OSS地址传入。每次创建消耗1次PSD上传额度。

请求参数

字段 类型 必填 说明
psdTitle string 是 PSD名称，最长100字符
psdKey string 否 自定义Key（唯一标识），不填则自动生成，最长64字符
psdUrl string 是 PSD文件的OSS地址

请求示例

POST /api/psd/create
Authorization: Bearer eyJ...
Content-Type: application/json

{
  "psdTitle": "我的设计稿",
  "psdKey": "my-design-001",
  "psdUrl": "https://pod.kity.me/psd/2026/03/18/abc123/design.psd"
}

响应示例

{
  "success": true,
  "message": "OK",
  "data": 42            // 新创建的PSD记录ID
}
注意：创建后PSD状态为 pending，系统会自动解析PSD文件。解析完成后状态变为 completed，解析失败则变为 failure。
DELETE /psd/remove/{id}

删除指定PSD记录，同时清理OSS上的相关文件。只能删除自己的PSD。

路径参数

字段 类型 说明
id int PSD记录ID

请求示例

DELETE /api/psd/remove/42
Authorization: Bearer eyJ...

响应示例

{
  "success": true,
  "message": "OK",
  "data": true
}
GET /psd/items

获取当前用户的PSD列表，支持分页、按状态和Key筛选。

查询参数

字段 类型 必填 说明
current int 否 页码，默认1
pageSize int 否 每页条数，默认20，最大100
status string 否 状态筛选，JSON数组，如 ["completed","pending"]
psdKeys string 否 按Key筛选，JSON数组，如 ["key1","key2"]

请求示例

GET /api/psd/items?current=1&pageSize=10&status=["completed"]
Authorization: Bearer eyJ...

响应 data.list 字段

字段 类型 说明
id int 记录ID
psdTitle string PSD名称
psdKey string PSD唯一Key
status string 状态：pending / processing / completed / failure
psdUrl string PSD源文件地址
parsedJsonUrl string 解析后的JSON地址
simpleJsonUrl string 精简JSON地址（含智能对象信息）
previewUrl string 预览图地址
renderCount int 渲染次数
filesize int 文件大小（字节）
createdAt string 创建时间
GET /psd/info/{psdKey}

根据 psdKey 获取PSD详情，用于渲染前获取解析数据。

路径参数

字段 类型 说明
psdKey string PSD唯一Key

请求示例

GET /api/psd/info/my-design-001
Authorization: Bearer eyJ...

响应 data 字段

字段 类型 说明
id int 记录ID
psdTitle string PSD名称
psdKey string PSD唯一Key
status string 状态
parsedJsonUrl string 解析JSON地址（渲染时加载此JSON）
simpleJsonUrl string 精简JSON地址
previewUrl string 预览图地址
renderCount int 渲染次数
filesize int 文件大小
createdAt string 创建时间
GET /psd/items-bykeys

根据多个 psdKey 批量获取PSD信息，适用于需要一次查询多个PSD的场景。最多支持50个Key。（需提供 apiToken 鉴权）

查询参数

字段 类型 必填 说明
psdKeys string 是 PSD Key列表，多个以英文逗号分隔，最多50个
apiToken string 是 用户的 API Token，可在用户控制台查看。系统会校验 Token 是否过期，以及 psdKeys 是否属于该 Token 对应的用户

请求示例

GET /api/psd/items-bykeys?psdKeys=my-design-001,my-design-002&apiToken=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

响应示例

{
  "success": true,
  "message": "OK",
  "data": [
    {
      "id": 42,
      "psdTitle": "我的设计稿",
      "psdKey": "my-design-001",
      "status": "completed",
      "parsedJsonUrl": "https://pod.kity.me/psd/.../output.json",
      "simpleJsonUrl": "https://pod.kity.me/psd/.../output_simply.json",
      "previewUrl": "https://pod.kity.me/psd/.../preview.jpg",
      "renderCount": 10,
      "filesize": 2048000,
      "createdAt": "2026-03-18 10:00:00"
    },
    ...
  ]
}
注意：此接口需提供 apiToken 参数进行鉴权。系统会校验 Token 是否有效、是否过期，以及请求的 psdKeys 是否属于该 Token 对应的用户。不存在的Key会被自动忽略。apiToken 可在用户控制台查看，有效期默认7天，管理员可调整。
POST /psd/render

提交渲染记录。前端完成渲染后调用此接口，扣减渲染次数并记录日志。每个 renderId 消耗1次渲染次数。

请求参数

字段 类型 必填 说明
psdKey string 是 PSD唯一Key
renderId string[] 是 渲染ID数组（16-64字符），1-20个
previewUrls object 否 渲染结果预览图，格式为 {renderId: url}

请求示例

POST /api/psd/render
Authorization: Bearer eyJ...
Content-Type: application/json

{
  "psdKey": "my-design-001",
  "renderId": [
    "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
  ],
  "previewUrls": {
    "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6": "https://pod.kity.me/tmp/render/26/0318/xxx.png"
  }
}

响应示例

{
  "success": true,
  "message": "OK",
  "data": true
}
GET /psd/render-logs

获取当前用户的渲染记录列表，支持分页。

查询参数

字段 类型 必填 说明
current int 否 页码，默认1
pageSize int 否 每页条数，默认20，最大100

响应 data.list 字段

字段 类型 说明
id int 记录ID
renderId string 渲染ID
previewUrl string 渲染结果预览图地址
psdTitle string 所属PSD名称
psdKey string 所属PSD Key
createdAt string 渲染时间
POST /psd/uploadToken

获取阿里云OSS STS临时上传凭证，用于前端直传文件至OSS。凭证有效期15分钟。

请求示例

POST /api/psd/uploadToken
Authorization: Bearer eyJ...

响应 data 字段

字段 类型 说明
accessKeyId string STS临时AccessKeyId
accessKeySecret string STS临时AccessKeySecret
securityToken string STS SecurityToken
expiration string 凭证过期时间（UTC）
bucket string OSS Bucket名称
region string OSS Region
endpoint string OSS Endpoint
domain string OSS自定义域名
dir string 本次上传的目录前缀，文件应传到此目录下
上传流程：先调用此接口获取凭证 → 使用 ali-oss SDK 或其他方式将PSD文件上传到 dir 指定的目录 → 拼接 domain + "/" + dir + filename 得到文件URL → 调用 创建PSD 接口传入该URL。

订单接口

POST /order/create

创建充值订单。订单创建后状态为 pending，管理员确认收款后标记为 paid，届时额度自动到账。

请求参数

字段 类型 必填 说明
psdCount int 是 购买PSD上传次数（≥0）
renderCount int 是 购买渲染次数（≥0）

psdCount 和 renderCount 不可同时为 0。

请求示例

POST /api/order/create
Authorization: Bearer eyJ...
Content-Type: application/json

{
  "psdCount": 10,
  "renderCount": 100
}

响应示例

{
  "success": true,
  "message": "OK",
  "data": {
    "orderCode": "20260318120000123456",   // 订单编号
    "amount": 1500                          // 应付金额（分）
  }
}
GET /order/items

获取当前用户的订单列表，支持分页、按状态和时间筛选。

查询参数

字段 类型 必填 说明
current int 否 页码，默认1
pageSize int 否 每页条数，默认20，最大100
status string 否 状态筛选，JSON数组，如 ["pending","paid"]
startTime string 否 开始时间，格式 YYYY-MM-DD HH:mm:ss
endTime string 否 结束时间，格式 YYYY-MM-DD HH:mm:ss

响应 data.list 字段

字段 类型 说明
id int 记录ID
orderCode string 订单编号
psdCount int 购买PSD次数
renderCount int 购买渲染次数
amount int 金额（分）
status string 状态：pending / paid
createdAt string 创建时间
paidAt string|null 支付时间
RenderPSD API 文档 · 如有疑问请联系客服 · 粤ICP备2026033784号-1