API 参考

RPICX DEVELOPER API

API 参考

rpicx-bed 图片/视频托管 REST API。所有接口根据项目 OpenAPI 规格自动生成，并按 tags 分类；public 免认证，user 需 Authorization: Bearer <JWT>，project 需 JWT 或项目级 API Key（X-API-Key），webhook 由服务端验签，internal 需 X-Agent-Secret。多数接口返回 {"code":"ok","data":...} 包装结构。

Base URL同域部署 / 本地开发后端

/同域部署（经 API 网关反代）
http://localhost:8080本地开发后端

125个接口5个分类OpenAPI 3.x

public→

GET/healthz健康检查 GET/openapi.yamlOpenAPI 规范文档 GET/docsSwagger UI 接口文档页面 GET/api/v1/system-configs公开系统配置列表（如默认容量、站点信息等）GET/api/v1/system-configs/media-base媒体基础 URL（CDN 地址或空，前端拼接媒体链接）GET/api/v1/plans在售套餐列表 GET/api/v1/payment/methods可用支付方式状态 POST/api/v1/auth/register邮箱注册（注册后自动授予默认容量）POST/api/v1/auth/login密码登录（命中 MFA 时返回 202 mfa_required）POST/api/v1/auth/refresh刷新令牌 POST/api/v1/auth/mfa/verify登录 MFA 验证（TOTP 验证码换取令牌）GET/api/v1/auth/oauth/github发起 GitHub OAuth 登录（302 跳转）GET/api/v1/auth/oauth/github/callbackGitHub OAuth 回调 GET/api/v1/auth/oauth/google发起 Google OAuth 登录（302 跳转）GET/api/v1/auth/oauth/google/callbackGoogle OAuth 回调 GET/api/v1/auth/oauth/statusOAuth 登录状态（当前是否处于 OAuth 流程）GET/api/v1/auth/methods启用的认证方式列表（密码/邮箱验证码/OAuth 提供商）POST/api/v1/auth/oauth/mfa/verifyOAuth 登录后的 MFA 验证 POST/api/v1/auth/phone-code/send发送手机号验证码（需启用手机号登录并配置短信服务）POST/api/v1/auth/login/phone-code手机号验证码登录或注册；新号码可绑定邮箱账号或创建账号 POST/api/v1/auth/phone-bind/email-code/send发送手机号绑定用邮箱验证码 POST/api/v1/auth/email-code/send发送登录邮箱验证码（每 IP 限频）POST/api/v1/auth/email-code/verify校验邮箱验证码（密码重置流程使用，不创建会话）POST/api/v1/auth/login/email-code邮箱验证码登录（未注册用户自动注册）POST/api/v1/auth/email-code/send-password发送密码重置邮箱验证码 POST/api/v1/auth/password/forgot忘记密码（发送重置验证码）POST/api/v1/auth/password/reset重置密码（需验证码）GET/api/v1/shares/{token}通过 token 解析公开分享（有密码时仅返回元信息）POST/api/v1/shares/{token}/verify校验分享密码（成功后返回资产与签名媒体 URL）GET/api/v1/shares/{token}/media分享媒体流（需 URL 携带 expire+sig 签名，支持 Range 请求）GET/media/{objectKey}公开媒体对象（存储代理：OSS 302 到 CDN，本地文件流式返回；非资产回退静态文件）HEAD/media/{objectKey}媒体对象 HEAD（同 GET）

webhook→

GET/api/v1/payment/webhooks/{provider}支付平台回调（部分平台支持 GET 确认）POST/api/v1/payment/webhooks/{provider}支付平台回调（验签后更新订单状态）POST/api/v1/moderation/callback内容审核异步结果回调（阿里云内容安全，checksum 验签）

user→

POST/api/v1/auth/logout退出登录（撤销指定会话或全部会话）POST/api/v1/auth/password/change修改密码（变更后使其他会话失效）POST/api/v1/auth/2fa/setup2FA 开启准备（返回 TOTP secret 与二维码信息）POST/api/v1/auth/2fa/enable启用 2FA（提交当前 TOTP 验证码确认）POST/api/v1/auth/2fa/disable禁用 2FA（需当前 TOTP 验证码）POST/api/v1/auth/2fa/recovery使用恢复码登录/恢复 2FA GET/api/v1/auth/2fa/status查询 2FA 启用状态 POST/api/v1/auth/2fa/recovery-codes重新生成恢复码（需当前 TOTP 验证码，旧恢复码作废）GET/api/v1/auth/oauth/{provider}/link绑定第三方账号（返回 provider 授权 URL）GET/api/v1/auth/oauth/identities已绑定的第三方身份列表 POST/api/v1/auth/oauth/identities/unlink解绑第三方身份 GET/api/v1/sessions当前用户的会话列表 DELETE/api/v1/sessions/{id}撤销指定会话 GET/api/v1/me当前用户资料（含存储用量/配额）PUT/api/v1/me更新当前用户资料（昵称/头像）GET/api/v1/me/capacity当前用户容量状态（有效配额、容量列表、是否可上传）GET/api/v1/timeline时间线（按拍摄/创建时间倒序分页，按天分组）GET/api/v1/geo/assets带地理信息的资产 GeoJSON GET/api/v1/entitlements当前用户权益（套餐与订阅）POST/api/v1/upload上传文件（multipart，字段 files[] 或 file；配额与限频保护）POST/api/v1/upload/tusTUS 分片上传初始化（头部 Upload-Length/Upload-Metadata/Content-Type）POST/api/v1/upload/tus/{id}TUS 合并完成上传（生成资产）PATCH/api/v1/upload/tus/{id}TUS 分片上传（头部 Upload-Offset 指定偏移）GET/api/v1/tokensAPI Token 列表 POST/api/v1/tokens创建 API Token DELETE/api/v1/tokens/{id}撤销 API Token POST/api/v1/assets/export导出资产（打包下载）GET/api/v1/assets/{id}资产详情（含元数据、媒体 URL、相邻资产、HLS/实况照片信息）DELETE/api/v1/assets/{id}删除资产（软删除进回收站，释放配额）DELETE/api/v1/assets/{id}/permanent永久删除回收站中的资产（不可恢复）POST/api/v1/assets/{id}/restore从回收站恢复资产（重新计入配额）GET/api/v1/trash回收站列表（含剩余保留天数，30 天自动清理）DELETE/api/v1/trash清空回收站（永久删除全部回收站资产）GET/api/v1/albums相册列表（游标分页）POST/api/v1/albums创建相册 GET/api/v1/albums/{id}相册详情 PUT/api/v1/albums/{id}更新相册（名称/描述/是否公开）DELETE/api/v1/albums/{id}删除相册 GET/api/v1/albums/{id}/assets相册内资产列表（游标分页）POST/api/v1/albums/{id}/assets相册资产管理（add/remove）POST/api/v1/albums/{id}/collaborators添加相册协作者 DELETE/api/v1/albums/{id}/collaborators/{user_id}移除相册协作者 GET/api/v1/shares我的分享列表 POST/api/v1/shares创建分享链接（可选密码与有效期）DELETE/api/v1/shares/{id}撤销分享 GET/api/v1/billing/summary账单摘要（套餐、订阅状态、存储用量/配额）GET/api/v1/billing/orders我的订单历史（limit/offset 分页）POST/api/v1/payment/orders创建支付订单（返回支付链接）POST/api/v1/payment/orders/{id}/sync同步订单支付状态（触发主动轮询补单）GET/api/v1/events/assets资产事件 SSE 流（上传/处理进度推送）GET/api/v1/media/{objectKey}登录用户媒体访问（可选 w= 参数取 WebP 缩略图变体；配置 CDN 时 302 跳转）GET/api/v1/certificates我的证书库列表 POST/api/v1/certificates上传证书（PEM 文本，校验私钥匹配与有效期）DELETE/api/v1/certificates/{id}删除我的证书（越权或不存在返回 400）

internal→

POST/api/v1/internal/health-reports节点 Agent 上报互探结果（批量投票）GET/api/v1/internal/peer-list获取对端节点列表（不含自身）

project→