用户端接口文档

本文档只描述终端用户 / 客户端需要调用的接口：注册登录、查询额度、调用 AI 功能、购买套餐。后台 CMS 管理接口不在本文范围内。

通用约定

鉴权

除注册、登录、查重、套餐列表等公开接口外，其余接口都需要在请求头带上用户凭证：

复制Authorization: Bearer utk_xxxxxxxx...

utk_ 开头的凭证由登录或注册接口返回。每次登录都会生成新凭证，旧凭证立即失效，客户端应把新凭证存起来替换旧的。

响应结构

成功：{ "code": 0, "message": "success", "data": {...} }

失败：{ "code": 402, "message": "积分不足…", "data": null }

判断逻辑：code === 0 即成功，其余一律失败。

计费与积分规则

用户的 points 就是可调用 AI 功能的次数。即梦 AI 4.6 每次调用扣 1 次（管理员可在后台「API 功能配置」里改单价）。

1. 先扣后调：接口在请求上游之前就扣除次数，不存在"调用了却没扣"的情况。
2. 余额不足直接拒绝：剩余次数 < 本次单价时返回 HTTP 402，不会调用上游，也不产生任何费用。
3. 上游失败自动返还：上游报错或超时（504）时自动退回本次额度，响应会写明「已返还 1 次额度，当前剩余 N 次」。
4. 入参不合法不扣费：缺 prompt、参考图不是合法图片等返回 400，在扣费之前拦截，额度不变。
5. 查余额：响应头 X-Points-Remaining、data.charge 明细，或随时调用 GET /api/users/me。

复制{ "code": 402, "message": "积分不足：本次需要 1 次调用额度，当前剩余 0 次，请先购买套餐", "data": null }

快速开始

复制# 1. 登录，拿到 token
curl -X POST https://www.jielafu.cn/api/users/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"123456"}'

# 2. 调用 AI 功能（扣 1 次额度）
curl -X POST https://www.jielafu.cn/api/call/jimeng_v46 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer utk_上面拿到的token" \
  -d '{"prompt":"赛博朋克风格的城市夜景"}'

注册

注册需要手机号 + 邮箱验证码，分两步完成。

第一步：获取邮箱验证码

复制curl -X POST https://www.jielafu.cn/api/users/send-code \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@qq.com"}'

复制{
  "code": 0,
  "message": "验证码已发送，请查收邮件（若无请检查垃圾箱）",
  "data": { "email": "alice@qq.com", "ttlMinutes": 5, "resendSeconds": 60 }
}

第二步：提交注册

注册成功即视为已登录，直接返回 token，无需再调一次登录。

复制curl -X POST https://www.jielafu.cn/api/users/register \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"123456","phone":"13800138000","email":"alice@qq.com","code":"123456"}'

复制{
  "code": 0,
  "message": "注册成功，已赠送 5 次调用额度",
  "data": {
    "token": "utk_9f3c...",
    "tokenType": "Bearer",
    "tokenUpdatedAt": "2026-10-05 03:20:11",
    "user": {
      "id": 12, "username": "alice", "nickname": "爱丽丝",
      "phone": "13800138000", "email": "alice@qq.com", "emailVerified": true,
      "points": 5, "usedPoints": 0, "status": "active",
      "lastLoginAt": null, "createdAt": "2026-10-05 03:20:11"
    }
  }
}

未开放注册返回 403；用户名 / 手机号 / 邮箱已被占用 409；手机号或邮箱格式不正确 400；验证码错误或过期 400。同一 IP 每小时最多注册 10 次。

登录 / 刷新 token

复制curl -X POST https://www.jielafu.cn/api/users/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"123456"}'

返回结构与注册一致。每次调用都会刷新 token，旧 token 立刻作废——在新设备登录会把旧设备顶下线。

我的信息

复制curl https://www.jielafu.cn/api/users/me -H "Authorization: Bearer utk_xxx"

复制{
  "code": 0,
  "data": {
    "id": 12, "username": "alice", "nickname": "爱丽丝",
    "phone": "13800138000", "email": "alice@qq.com", "emailVerified": true,
    "points": 42, "usedPoints": 8, "status": "active",
    "lastLoginAt": "2026-10-05 03:20:11",
    "createdAt": "2026-10-05 03:10:02",
    "tokenUpdatedAt": "2026-10-05 03:20:11"
  }
}

points 剩余可调用次数，usedPoints 累计已消耗。phone / email 为注册时填写，emailVerified 表示邮箱是否已通过验证码校验。

points — 剩余可调用次数；usedPoints — 累计已消耗次数。

退出登录

清空服务端凭证，当前 token 立即失效，需要重新登录。

修改密码

成功后返回新 token，旧 token 立即失效（其它设备会被下线），客户端需保存新凭证。原密码不正确返回 400。

查重与注册开关

客户端可据此决定是否展示注册入口，以及是否需要提示「邮件服务未配置」。

复制{
  "code": 0,
  "data": {
    "enabled": true,
    "giftPoints": 5,
    "requirePhone": true,
    "requireEmailCode": true,
    "mailConfigured": true
  }
}

enabled 是否开放注册；giftPoints 注册赠送次数；requirePhone / requireEmailCode 是否强制手机号与邮箱验证码；mailConfigured 为 false 时无法发送验证码。

复制{ "code": 0, "data": { "username": "alice", "formatOk": true, "available": false } }

formatOk 格式是否合法，available 是否未被占用，可用于注册表单实时校验。

可用功能列表

后台配置了哪些 AI 能力，客户端不需要关心上游地址与密钥——只需要知道功能标识 code 和该功能的参数。

复制{
  "code": 0,
  "data": {
    "list": [
      {
        "code": "jimeng_v46",
        "name": "即梦 AI 4.6 文生图",
        "description": "输入提示词生成图片，每次调用扣除 1 次额度",
        "costPoints": 1,
        "paramSchema": [
          { "key": "prompt", "label": "提示词", "type": "string", "required": true },
          { "key": "width",  "label": "宽度",   "type": "number", "required": false, "default": 2048, "min": 512, "max": 4096 }
        ]
      }
    ]
  }
}

通用调用

复制curl -X POST https://www.jielafu.cn/api/call/jimeng_v46 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer utk_xxx" \
  -d '{"prompt":"赛博朋克风格的城市夜景","width":2048,"height":2048}'

复制{
  "code": 0,
  "message": "调用成功",
  "data": {
    "feature": "jimeng_v46",
    "name": "即梦 AI 4.6 文生图",
    "cost": 1,
    "charge": { "before": 42, "after": 41, "amount": 1 },
    "result": { "images": ["https://..."], "taskId": "..." },
    "elapsedMs": 18320
  }
}

响应头：X-Points-Remaining: 41

图生图（传入参考图）

即梦 4.6 的文生图与图生图共用同一个功能标识，区别只在于有没有传参考图。

两种方式可混用，合计最多 14 张；建议不超过 6 张——图片越多越大，处理时间越长，超过 6 张后参考效果反而下降。单张限制：JPEG / PNG，≤ 15 MB，分辨率 ≤ 4096×4096。

参考图已在公网（推荐）

curl -X POST https://www.jielafu.cn/api/call/jimeng_v46 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer utk_xxx" \
  -d '{
    "prompt": "把这张图的背景换成夜晚的城市霓虹灯光，写实摄影风格",
    "imageUrls": ["https://example.com/cat.jpg"]
  }'

参考图在本地（传 base64，由服务器托管）

const fs = require('fs');

const b64 = fs.readFileSync('./cat.jpg').toString('base64');
const r = await fetch('https://www.jielafu.cn/api/call/jimeng_v46', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Authorization: 'Bearer utk_xxx' },
  body: JSON.stringify({
    prompt: '把这张图的背景换成夜晚的城市霓虹灯光，写实摄影风格',
    images: [b64],
  }),
}).then((x) => x.json());

即梦 AI 4.6 生图

功能标识为 jimeng_v46 时，也可用下面这组专用接口（参数更完整；计费规则一致，每次扣 1 次额度）。

同步生成（推荐）

提交任务后服务端自动轮询，直接返回成品图。

复制curl -X POST https://www.jielafu.cn/api/jimeng/generate \
  -H "Content-Type: application/json" -H "Authorization: Bearer utk_xxx" \
  -d '{"prompt":"一只坐在窗台上的橘猫，午后阳光，写实风格"}'

复制{
  "code": 0,
  "message": "生成完成，共 1 张",
  "data": {
    "feature": "jimeng_v46",
    "taskId": "cgt-...",
    "status": "done",
    "images": ["https://.../xxx.jpeg"],
    "waitedMs": 15230,
    "charge": { "before": 42, "after": 41, "amount": 1 }
  }
}

异步提交 + 查询结果

参数同上，返回 { taskId, requestId }，状态码 201。

复制{ "code": 0, "data": { "taskId": "cgt-...", "status": "done", "images": ["https://..."], "finished": true } }

status 取值：pending（排队中）／running（生成中）／done（完成）／failed、error、expired、not_found（终态失败）。finished: true 表示已到终态，可停止轮询。

手动扣减额度

供外部系统直接扣次数（不走上游调用）。feature 默认 manual，count 默认 1。

复制{ "code": 0, "message": "已扣除 1 次调用额度", "data": { "before": 42, "after": 41, "cost": 1 } }

使用统计

复制{
  "code": 0,
  "data": {
    "points": 41,
    "usedPoints": 8,
    "rechargedPoints": 105,
    "byFeature": [ { "feature": "jimeng_v46", "total": 6, "count": 6 } ],
    "daily": [ { "day": "2026-10-05", "total": 3 } ],
    "orders": { "count": 2, "paidAmount": 49, "paidPoints": 100 }
  }
}

byFeature — 按功能聚合的消耗次数与笔数（最多 10 项）；daily — 近 14 天每天消耗次数；orders — 累计订单数、已付金额（元）、已到账次数。

额度流水

复制{
  "code": 0,
  "data": {
    "points": 41,
    "list": [
      { "id": 88, "type": "consume", "amount": -1, "beforePoints": 42, "afterPoints": 41,
        "feature": "jimeng_v46", "remark": "", "createdAt": "2026-10-05 03:31:02" },
      { "id": 87, "type": "recharge", "amount": 100, "beforePoints": 5, "afterPoints": 105,
        "feature": "", "remark": "订单 ORD... 到账", "createdAt": "2026-10-05 03:25:44" }
    ]
  }
}

type 取值：init（注册赠送）／recharge（购买到账）／consume（调用消耗）／adjust（管理员调整或失败返还）。

我的作品（创作记录）

每次调用 AI 生成成功后，系统会自动记一条作品：提示词、参数、消耗次数，以及图片原文（base64）。调用方不需要额外传参，落库在服务端完成。

分页查询我的作品

复制{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 41,
        "title": "一只坐在窗台上的橘猫，午后阳光",
        "prompt": "一只坐在窗台上的橘猫，午后阳光，写实摄影风格",
        "featureCode": "jimeng_v46",
        "status": "success",
        "imageCount": 1,
        "totalBytes": 3125736,
        "costPoints": 1,
        "elapsedMs": 10289,
        "createdAt": "2026-10-09 18:35:12",
        "images": [
          { "id": 47, "sortOrder": 0, "mime": "image/png", "bytes": 3125736,
            "preview": "/works/2026-10/mv0tvhqq-2f71a78b5100d3d8.png", "url": "" }
        ]
      }
    ],
    "pagination": {
      "page": 1, "pageSize": 10, "total": 37,
      "totalPages": 4, "hasMore": true, "nextPage": 2
    }
  }
}

翻页用 pagination 里的字段：hasMore 判断是否还有下一页，nextPage 直接给出下一页页码，totalPages 用于展示总页数。默认按最新在前排序。

images[].preview 是站内可直接访问的图片链接，拼上站点域名就能显示：

复制https://www.jielafu.cn/works/2026-10/mv0tvhqq-2f71a78b5100d3d8.png

预览文件被清理后，服务端会用库里的 base64 自动重建，链接不会失效；真正的图片原文始终存在数据库里。

作品详情

返回单条作品（含 images 数组，默认带 preview，加 base64=1 时附原文）。查别人的作品返回 404。

删除作品

图片记录一并删除。只能删自己的，删别人的返回 404。

套餐列表

复制{
  "code": 0,
  "data": [
    { "id": 1, "name": "体验包", "code": "starter", "price": 9.9, "points": 10, "description": "10 次调用额度" },
    { "id": 2, "name": "标准包", "code": "standard", "price": 49,  "points": 100, "description": "100 次调用额度" }
  ]
}

price 单位元，points 为到账次数。

下单购买

复制curl -X POST https://www.jielafu.cn/api/orders \
  -H "Content-Type: application/json" -H "Authorization: Bearer utk_xxx" \
  -d '{"packageCode":"standard"}'

复制{
  "code": 0,
  "message": "下单成功，待支付",
  "data": {
    "id": 31, "orderNo": "ORD20261005033102a1b2",
    "packageName": "标准包", "amount": 49, "points": 100,
    "payStatus": "pending", "createdAt": "2026-10-05 03:31:02"
  }
}

我的订单

payStatus 可筛 pending / paid / refunded，不传返回全部。

复制{
  "code": 0,
  "data": [
    { "id": 31, "orderNo": "ORD...", "packageName": "标准包", "amount": 49, "points": 100,
      "payStatus": "paid", "payMethod": "wechat", "paidAt": "2026-10-05 03:33:10",
      "createdAt": "2026-10-05 03:31:02" }
  ]
}

取消我的订单

只有待支付订单可以取消，且只能取消自己的订单。已支付或已取消的订单返回 409。

错误码

完整示例

复制BASE=https://www.jielafu.cn

# 1. 登录
TOKEN=$(curl -s -X POST $BASE/api/users/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"123456"}' | grep -o '"token":"[^"]*"' | cut -d'"' -f4)
echo "token: $TOKEN"

# 2. 查余额
curl -s $BASE/api/users/me -H "Authorization: Bearer $TOKEN"

# 3. 看有哪些 AI 功能
curl -s $BASE/api/call

# 4. 调用即梦生图（扣 1 次）
curl -s -X POST $BASE/api/call/jimeng_v46 \
  -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -d '{"prompt":"赛博朋克风格的城市夜景"}'

# 5. 买套餐
curl -s -X POST $BASE/api/orders \
  -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -d '{"packageCode":"standard"}'

JavaScript

复制const BASE = 'https://www.jielafu.cn';
let token = localStorage.getItem('token');

async function api(path, body) {
  const res = await fetch(`$https://www.jielafu.cn${path}`, {
    method: body ? 'POST' : 'GET',
    headers: {
      'Content-Type': 'application/json',
      ...(token ? { Authorization: `Bearer ${token}` } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json();
  if (json.code !== 0) throw new Error(`${json.code} ${json.message}`);
  return json.data;
}

// 登录：每次都要把新 token 存起来（旧的会失效）
const { token: t } = await api('/api/users/login', { username: 'alice', password: '123456' });
token = t;
localStorage.setItem('token', t);

// 调用 AI
const r = await api('/api/call/jimeng_v46', { prompt: '一只橘猫' });
console.log(r.result.images);

接入须知