雨落开发者文档

开发者 API 文档

用于开发者自有应用的用户登录、会话校验、聊天与生图。开发者自有用户与雨落主站账户相互隔离。

接入前准备

获批开发者、测试账号或管理员可在控制台「登录鉴权」创建应用实例；开发者后台可创建 API Key。完整密钥只显示一次，必须仅保存在你的服务端环境变量或密钥库中，绝不可写入 App、网页 JavaScript、Git 仓库、日志或截图。

01通用约定与鉴权

生产基础地址为 https://zer-zero.cn。开发者接口均使用 JSON 请求与 JSON 返回，除云盘下载外均为 POST。时间字段为 Unix 时间戳（秒）；所有请求均应使用 HTTPS。

项目格式与含义
开发者 API KeyAuthorization: Bearer yuluo-…。每个开发者接口都必须携带，用于识别开发者账户。
Content-Typeapplication/json。除文件下载外必填。
X-Request-Id聊天、生图必填，16–200 个字符。每次业务请求使用新的随机 ID；重复 ID 会被拒绝，不会返回旧结果。
用户会话登录成功返回的 accessToken。聊天、生图、校验与退出时在请求体中提交。
curl -X POST https://zer-zero.cn/api/developer/v1/auth/login \
  -H 'Authorization: Bearer yuluo-你的开发者密钥' \
  -H 'Content-Type: application/json' \
  -d '{"username":"demo_user","password":"your-password"}'

统一错误格式：{"ok":false,"error":"错误原因"}。客户端应根据状态码提供重试或登录入口，不要把服务端错误原样展示给终端用户。

02开发者自有用户与登录

开发者自有用户由开发者后台创建和管理，不是雨落主站用户，不能访问主站余额、微信、聊天记录、云盘或任何主站会话。用户名为 3–100 个字符，只可含字母、数字与 _ @ . + -；密码长度为 8–128 个字符。

登录

POST /api/developer/v1/auth/login
Authorization: Bearer yuluo-…
Content-Type: application/json

{
  "username": "demo_user",
  "password": "correct-horse-battery-staple"
}
请求字段必填含义
username是开发者后台创建的自有用户名。
password是该自有用户的密码；不会在任何成功响应中返回。

未开启双重认证时，200：

{
  "ok": true,
  "requiresTwoFactor": false,
  "tokenType": "Bearer",
  "accessToken": "用户会话令牌",
  "expiresAt": 1780000000.0,
  "expiresIn": 86400,
  "user": {
    "id": "32 位用户 ID", "username": "demo_user",
    "twoFactorEnabled": false, "balance": "20.000000",
    "balanceMicros": 20000000, "isBanned": false,
    "banReason": "", "createdAt": 1780000000.0, "updatedAt": 1780000000.0
  }
}

accessToken 有效期 24 小时。balance 是便于展示的十进制字符串；balanceMicros 以百万分之一元为单位，适合精确计算。

开启 TOTP 双重认证时，202：

{"ok":true,"requiresTwoFactor":true,"challengeId":"一次性挑战 ID","expiresAt":1780000300.0}

挑战 5 分钟后失效，且与发起登录的 IP 绑定。下一步将验证器中的六位 TOTP 代码提交到双重认证接口。

03双重认证、会话校验与退出

完成 TOTP 双重认证

POST /api/developer/v1/auth/2fa/verify
Authorization: Bearer yuluo-…
Content-Type: application/json

{"challengeId":"登录响应中的 challengeId","code":"123456"}

成功时返回 200，结构与普通登录成功响应相同（包含 accessToken、expiresAt 与 user）。验证码已使用、过期、网络变化或连续失败时返回 401；请重新开始登录，不能重放旧挑战。

校验会话

POST /api/developer/v1/auth/introspect
Authorization: Bearer yuluo-…
Content-Type: application/json

{"accessToken":"用户会话令牌"}

// 有效会话
{"ok":true,"active":true,"user":{"id":"…","username":"demo_user","expiresAt":1780000000.0}}

// 无效、过期、已注销或开发者权限被撤销
{"ok":true,"active":false,"user":null}

退出并撤销会话

POST /api/developer/v1/auth/logout
Authorization: Bearer yuluo-…
Content-Type: application/json

{"accessToken":"用户会话令牌"}

// 响应
{"ok":true,"revoked":true}

revoked 表示本次是否实际删除了有效会话。客户端应在本地同时清除令牌，无论它是 true 还是 false。

04聊天模型中转

聊天由服务端调用当前管理员启用的模型。每次调用须提交开发者自己的用户会话与该用户的人设，Token 消费计入开发者账户，审计记录会记下请求 IP、自有用户和用量。

POST /api/developer/v1/ai/chat
Authorization: Bearer yuluo-…
Content-Type: application/json
X-Request-Id: chat_01JQ2A4P6K7M8N9R0S1T

{
  "userAccessToken": "登录后返回的 accessToken",
  "persona": "你是一位简洁、温暖且尊重用户边界的聊天伙伴。",
  "messages": [{"role":"user","content":"今天适合做什么？"}],
  "model": "可选：控制台显示的已启用模型名称",
  "temperature": 0.8,
  "maxTokens": 800
}
字段必填规则
userAccessToken是有效的开发者自有用户会话。
persona是10–8000 字符；服务端会追加不可覆盖的安全规则。
messages是1–50 条；每条仅可为 user 或 assistant，内容 1–12000 字符，总计最多 30000 字符。
model否未填写时使用默认模型；填写时必须是控制台所列的已启用模型。
temperature否0–1.5，默认 0.8。
maxTokens否1–1500，默认 800。

成功响应，200：

{
  "ok": true, "id": "chatcmpl-随机请求标识", "model": "实际使用的模型名称",
  "message": {"role":"assistant","content":"可以先…"},
  "usage": {"promptTokens":120,"completionTokens":86,"totalTokens":206,"estimated":false}
}

usage 是本次实际或估算 Token 用量；estimated=true 表示上游未返回完整用量，服务端已按规则估算并计费。相同 X-Request-Id 不会重复执行或计费，而是返回 403。

05生图模型中转

生图在服务端完成，调用前需要有效开发者 API Key、有效自有用户会话及新的 X-Request-Id。每张图按当前价格从开发者账户扣费，响应图片以 Base64 返回，客户端需自行解码显示或保存。

POST /api/developer/v1/ai/images
Authorization: Bearer yuluo-…
Content-Type: application/json
X-Request-Id: image_01JQ2A4P6K7M8N9R0S1T

{
  "userAccessToken": "登录后返回的 accessToken",
  "prompt": "清晨窗边的一杯热咖啡，写实摄影，自然光",
  "size": "1024x1536", "quality": "medium",
  "model": "可选：当前已启用生图模型名称"
}
字段必填规则
userAccessToken是有效的开发者自有用户会话。
prompt是1–12000 字符。
size否默认 1024x1024；支持 1024x1024、1024x1536、1536x1024、2048x1152、1152x2048。
quality否low、medium 或 high，默认 medium。
model否未填写使用当前线路模型；填写时必须与当前启用模型完全一致。

成功响应，200：

{
  "ok": true, "id": "img-随机请求标识", "created": 1780000000,
  "model": "实际使用的模型名称", "size": "1024x1536", "quality": "medium",
  "data": [{"b64_json":"iVBORw0KGgoAAAANSUhEUg…","mime_type":"image/png"}]
}

b64_json 是图片二进制的 Base64 字符串，不是 URL；mime_type 用于生成正确扩展名与预览类型。请避免把完整 Base64 写入业务日志。

06accept_token 身份验证

accept_token 是某个雨落账户为外部应用签发的身份验证凭据，不等同于开发者 API Key。它只能验证该雨落账户身份，不能登录主站、操作账户或自行提升权限。完整令牌仅在创建时展示一次。

POST /api/accept-token/v1/verify
Authorization: Bearer accept_…
Content-Type: application/json

{
  "permissions": "camera,location",
  "workingDirectory": "/Applications/MyApp",
  "osVersion": "iOS 26.0 / MyApp 1.0"
}

令牌也可放入 X-Yuluo-Accept-Token 请求头，或放入请求体 acceptToken 字段；优先级依次为 Authorization、X-Yuluo-Accept-Token、请求体。permissions、workingDirectory、osVersion 都是可选审计信息，绝不会被服务端用来授予权限。

成功响应，200：

{
  "ok": true, "authenticated": true,
  "user": {"name":"自定义显示名称","avatar":"/api/accept-token/v1/avatar","avatarUrl":"/api/accept-token/v1/avatar","hasCustomAvatar":true,
    "roles":{"admin":false,"test":true,"developer":false}}
}

name 为用户设置的显示名称，未设置时默认邮箱；avatar/avatarUrl 为需携带同一 accept_token（Authorization: Bearer … 或 X-Yuluo-Accept-Token）才能读取的 JPEG/SVG 头像地址。hasCustomAvatar 为 false 时请使用纯白默认头像。

令牌无效响应，401： {"ok":false,"authenticated":false,"error":"accept_token 无效"}。无论成功、失败或格式错误，系统均记录时间、来源 IP、调用方上报环境和结果；角色只由服务端账户状态计算，调用方提交的角色字段不会生效。

07有限云盘下载与错误处理

仅当雨落账户在对应应用实例的「雨落云盘下载白名单」中明确勾选某一个文件，accept_token 才可下载该精确文件。它没有目录列表、搜索、预览、上传、改名、移动或删除能力；白名单为空即无云盘访问权。

GET /api/accept-token/v1/files/drv_FILE_ID/download
Authorization: Bearer accept_…
X-Yuluo-Client-Permissions: storage-read
X-Yuluo-Client-Workdir: /Applications/MyApp
X-Yuluo-Client-OS: iOS 26.0 / MyApp 1.0

成功时返回文件二进制流，响应头含 Content-Type、Content-Disposition: attachment; filename=… 与 Cache-Control: no-store。文件标识不是目录权限；即使猜到其他 drv_… 标识也会返回 403。

状态码含义与客户端建议
200请求完成；解析业务字段或下载文件。
201资源创建成功；控制台创建 API Key、应用实例或自有用户时使用。
202需要完成 TOTP 双重认证；保存 challengeId 后引导用户输入验证码。
400字段缺失、类型错误、长度超限或模型/尺寸不受支持；修正参数后使用新的请求 ID 重试。
401开发者 API Key、accept_token 或用户会话无效/过期；清除本地凭据并重新登录或重新授权。
403权限不足、账户异常、余额不足、会话无效、重复请求，或云盘文件未获授权；不要自动无限重试。
502上游模型或生图服务暂时不可用；可指数退避重试，并始终生成新的 X-Request-Id。

撤销开发者权限、轮换 API Key、删除应用实例、移除云盘白名单文件或封禁相关账户后，相应凭据会立即失效。请为密钥泄露、登录失效和网络错误设计明确的本地清理与重新授权流程。