App 接口

首次接入先查看快速接入与公共协议。

左侧按功能模块展开,默认定位当前页面所在模块;搜索支持模块名、接口名称和路径。下方索引与左侧模块一致。

闪屏布局

接口 方法 路径
获取闪屏布局配置 GET /api/v1/app/bootstrap

新客户端先匿名读取IP布局:CN国内、其他已识别地区国际、无法识别默认国内,再展示地区相关协议和登录布局。语言、发行渠道、账号与支付各自独立;网络请求失败仍需重试,不能当作IP回退。新协议目录使用layoutPolicy=ip-v1,具体见独立契约。

登录与会话

接口已实现;当前dev手机号与邮箱统一使用固定验证码123456,先申请挑战再验证,不实际发送短信邮件。开发身份与真实身份隔离,后续再切换真实供应商和HTTPS。调用顺序见登录注册接入。

验证码申请的限流提示优化区分60秒冷却与小时额度,并提供Retry-After剩余秒数;错误码保持兼容。准确字段及发布状态见发送登录验证码。

手机与邮箱统一在获取验证码时提示账号封禁;返回403 ACCOUNT_BANNED时不生成挑战、不投递、不进入验证码输入页。验证码登录、刷新、受保护业务和长连接仍由服务端拦截,发码前提示不会取代后续检查;匿名阶段不公开原因或期限,见封禁接入。

接口 方法 路径
获取登录方式与协议版本 GET /api/v1/auth/options
发送登录验证码 POST /api/v1/auth/challenges
验证码登录 POST /api/v1/auth/verify-code
申请三方登录挑战 POST /api/v1/auth/providers/challenges
验证三方登录 POST /api/v1/auth/providers/login
刷新登录凭证 POST /api/v1/auth/refresh
退出登录 POST /api/v1/auth/logout
退出账号会话(兼容路径) POST /api/v1/auth/logout-all

协议阅读

接口 方法 路径
获取四类协议网页地址(中英日韩) GET /api/v1/agreements
读取精确协议版本 GET /api/v1/agreements/{type}/{contentVersion}
打开已生效协议网页 GET /legal/agreements/{id}

新客户端使用layoutPolicy=ip-v1,按与闪屏相同的后端IP规则选择国内/国际,未知默认国内;无参数旧客户端继续渠道兼容。国内四类中文、国际四类各中英日韩,不接收App自选法域/地区;缺译文不跨范围替代,未发布返回不可用。实现与验证状态见独立契约。

协议后台保存成功即生效,App下一次目录读取即可获得链接。requiredVersion与登录termsVersion/privacyVersion共用当前同意快照,contentVersion为独立正文版本,允许不同;历史正文和用户同意保留。客户端版本变化时刷新配置并重新明确同意,不能自动勾选或重用旧验证码挑战。

注册资料

客户端继续在统一请求层发送X-Channel等公共请求头。旧账号渠道为空时,服务端在后续合法登录、刷新或Bearer认证请求中补录一次,无需新接口;已有渠道保持。

登录响应直接返回持久化registrationStep,仅取1–4,不新增进度接口;VIP不计入资料步骤。registrationStatus=COMPLETE后再根据vipRequired决定VIP页或首页;当前渠道vipGateEnabled和服务端vipActive分别返回,默认关闭门槛。刷新及本人资料等既有接口返回同一组字段,见两层准入。

接口 方法 路径
获取当前用户与注册进度 GET /api/v1/me
保存注册资料草稿 PATCH /api/v1/me/registration
完成注册 POST /api/v1/me/registration/complete

国家与字典

接口 方法 路径
获取支持的国家与地区(热门排序、四语、图标) GET /api/v1/catalogs/countries
读取国家与地区图标 GET /api/v1/media/country-flags/{countryCode}
获取支持的资料语言(我会的/学习语言) GET /api/v1/catalogs/languages
获取注册字典 GET /api/v1/catalogs/registration

新增国家列表及国旗读取入口已随整合版本部署到当前开发API,旧注册字典的热门排序随同发布;公网四语目录与国旗读取已核对。Flutter仍需迁移到新接口,具体字段、排序与验证范围见各自契约。

独立资料语言入口已部署,返回当前10种语种的四语名称、原生名称、文字标记和预设热门排名;“我会的/学习语言”共用并直接保持服务器顺序,Flutter尚需从旧注册字典迁移。App界面语言设置仍独立维护。

兴趣标签

完整目录提供分类、四语文字、图标及可选状态,注册和资料编辑共用;后台保存即生效,停用保留历史显示,新选择仍限制1–6个。

接口 方法 路径
读取完整兴趣标签目录 GET /api/v1/catalogs/interests
读取兴趣标签图标 GET /api/v1/media/interest-icons/{id}

首页最新人物

首页“最新”人物列表使用服务端最近活跃时间排序;公开资料、VIP、在线租约和活跃时间一次返回,客户端不逐人请求用户主页。未知活跃时间的账号不进入结果,依赖失败整页返回503。

接口 方法 路径
读取首页最新人物 GET /api/v1/home/latest

资料编辑

国家/地区实际变更仅限当前有效VIP;非VIP返回403 PROFILE_COUNTRY_VIP_REQUIRED。提交原国家、不传或null不限制其他字段,首次注册选国家保持原流程;详见保存资料。

本人资料、编辑读取/保存、注册保存/完成均返回data.completionPercent,“我的”主页返回data.account.completionPercent;统一为0–100整数,规则见资料完善度,无需额外请求。

编辑首屏只用GET /me/profile读取完整本人资料及display中的所选国家、两种语言、兴趣名称与图标;原PATCH也直接返回最新display。完整可选目录在打开选择器时加载,媒体复用原路径和缓存;version与moderation仍随资料返回。

注册和资料编辑的昵称统一为1–8个UTF-16代码单元,去除首尾空白后不能为空;历史昵称按原值保留。我会的语言与想学习的语言必须不同,部分修改按已存资料合并校验,完成注册再次检查;重复返回400 PROFILE_LANGUAGES_SAME。注册后独立编辑;介绍保持30字符,兴趣1–6个,相册0–9张。上传只暂存,资料页带version统一保存。

接口 方法 路径
读取可编辑本人资料 GET /api/v1/me/profile
保存本人资料与相册 PATCH /api/v1/me/profile

互动视频不要求前端上传首帧:后端在OSS上传确认时截取起始画面并保存,动态列表/详情返回media.posterUrl,本人主页复用已存封面。失败、编码及历史空值范围见上传确认。

头像与相册

文件统一OSS直传并由JSON确认后暂存,资料保存后才绑定;五个旧App multipart POST入口已移除并返回410,旧安装包须更新。图片归属、数量限制及权限见各接口。

接口 方法 路径
申请OSS单文件直传(全部已有媒体用途) POST /api/v1/media/uploads
确认OSS上传并取得原媒体回执 POST /api/v1/media/uploads/{uploadId}/complete
取消未确认OSS上传 DELETE /api/v1/media/uploads/{uploadId}
批量获取媒体交付信息 POST /api/v1/media/downloads
申请CDN媒体凭证 POST /api/v1/media/credentials
CDN专用远程鉴权回调(App不直调) GET /api/v1/media/cdn/authorize
读取本人上传头像 GET /api/v1/media/avatars/{id}
读取本人相册照片 GET /api/v1/media/album-photos/{id}
读取用户已审公开相册照片 GET /api/v1/media/user-albums/{userId}/{photoId}
丢弃未保存的相册照片 DELETE /api/v1/media/album-photos/{id}

头像、昵称和个性签名采用逐项资料审核,本人读取新增moderation反馈;上传或保存成功不等于公开。公开资料字段只取已审值,avatarUrl统一由媒体入口按Bearer身份选择本人最新已保存绑定头像或他人已审公开头像,无对应引用才用默认图,前端直接加载返回地址。

我的与设置

「我的」首屏使用主页汇总一次读取资料、所选国家/语言名称、关系、钱包和动态/点赞总数及最近三条动态的多图缩略索引与照片张数,以及最多三位最近访客的userId/avatarUrl/vipActive(访客自己的当前有效会员状态);访客总数继续取relationships.visitors,不额外拼接关系列表或逐人资料请求;编辑、列表及安全操作在进入二级页面后按需使用下列接口。关系列表各项新增非空boolean vipActive,表示本条用户的有效VIP,访客及其他kind共用。完整范围见我的与设置接入,最新部署与验证以对应接口文档为准;真实支付及即时客服仍有独立未实现边界。

用户详情昵称页头使用identity.nickname;capabilities提供真实举报/拉黑/取消拉黑能力,本人禁用面向他人操作。我方屏蔽时只返回BLOCKED_BY_ME最小身份与能力,完整资料为null,受保护媒体和动态仍不可见;用户举报为独立真实用户收件,不使用动态ID。

用户主页主体一次返回目标已审资料、VIP、生日及服务端年龄、长连接租约状态、三项关系数、已审相册、所选目录和操作能力;动态继续独立分页。相册照片使用公开相册媒体逐次鉴权;空公开相册隐藏整段,依赖错误不伪装空数据。聊天尚未实现真实会话,canChat=false;三项统计只展示,不开放他人关系列表。

接口 方法 路径
读取我的主页汇总 GET /api/v1/me/home
读取本人账号与安全 GET /api/v1/me/account
申请当前绑定验证码 POST /api/v1/me/account/verification-challenges
验证当前绑定并取得操作凭证 POST /api/v1/me/account/verification-proofs
申请新绑定验证码 POST /api/v1/me/account/binding-challenges
更换本人登录绑定 PUT /api/v1/me/account/binding
读取注销条件与计划 GET /api/v1/me/account/deletion
提交本人账号注销 POST /api/v1/me/account/deletion
读取本人通知偏好 GET /api/v1/me/settings/notifications
保存本人通知偏好 PATCH /api/v1/me/settings/notifications
读取本人关系统计 GET /api/v1/me/relationships/counts
读取本人关系或黑名单(分页及四语展示) GET /api/v1/me/relationships
确认粉丝列表已读 PUT /api/v1/me/relationships/followers/read
关注用户 PUT /api/v1/me/following/{userId}
取消关注用户 DELETE /api/v1/me/following/{userId}
屏蔽用户 PUT /api/v1/me/blocked-users/{userId}
解除屏蔽用户 DELETE /api/v1/me/blocked-users/{userId}
读取用户主页主体 GET /api/v1/users/{userId}/profile
举报用户 POST /api/v1/users/{userId}/reports
按登录身份读取用户头像及默认图 GET /api/v1/media/user-avatars/{userId}
读取本人钱包余额 GET /api/v1/me/wallet
读取钱包充值套餐 GET /api/v1/me/wallet/recharge
读取本人收支明细 GET /api/v1/me/wallet/entries

我的动态与点赞

接口 方法 路径
读取我的动态 GET /api/v1/me/posts
读取我的点赞动态(分类分页与全部总数) GET /api/v1/me/liked-posts
发布个人动态 POST /api/v1/posts
读取动态详情 GET /api/v1/posts/{id}
删除本人动态 DELETE /api/v1/posts/{id}
点赞动态 PUT /api/v1/posts/{id}/like
取消动态点赞 DELETE /api/v1/posts/{id}/like
读取动态图片 GET /api/v1/media/post-photos/{id}
丢弃动态暂存图片 DELETE /api/v1/media/post-photos/{id}

实时连接

接口 方法 路径 状态
建立长连接 WebSocket Upgrade /ws/v1/realtime 心跳、票据、Redis 路由已验证
申请连接票据 POST /api/v1/realtime/tickets 入口已实现,待真实登录联动
申请开发联调票据 POST /api/v1/realtime/dev-tickets 仅local/dev且非prod配置,独立密钥保护

本阶段只提供连接架构,消息持久化、已读、离线补拉和聊天业务另行接入。

系统与安全

设备限制与封禁提示见封禁接入,以下API已部署、Flutter配套进行中;设备采集必须在明确同意后执行,现有安装UUID不替换,设备强制开关保持关闭。提交申诉复用当前App主接口,开发固定码HTTP例外可直接申请,不依赖设备专用地址;设备材料及正式申诉继续HTTPS。

接口 方法 路径 状态
读取设备风控策略 GET /api/v1/security/device-policy API已部署,客户端配套中
提交设备安全检查 POST /api/v1/security/device-check API已部署,始终HTTPS,设备启用待验收
提交封禁申诉 POST /api/v1/security/access-appeals 同次限制只提交一次,重登恢复已提交状态
接口 方法 路径 状态
检查App版本升级 GET /api/v1/app/updates 已部署,客户端更新接入待完成
获取系统信息 GET /api/v1/system/info 已联调
标准请求测试 POST /api/v1/system/request-test 仅dev且非prod配置,已联调
获取接口加密公钥 GET /api/v1/security/encryption-key 已部署,AES 接入入口

JSON 接口可按AES 加密协议使用相同路径收发密文;业务字段仍以各自独立文档为准。

服务地址

翻译统一遵循文字翻译规则:DeepSeek非思考模式和十语目标;默认按当前App界面语言、本人会的语言、英文回退。App移除固定中文目标,实际值取响应targetLanguage;未取到界面语言时不提前补英文。供应商和客户端验收范围分别说明。

https://api.budyoo.cn

当前为唯一正式部署环境,处于上线前阶段,没有独立测试服;公网HTTPS已验收,实际运行配置仍为dev。认证数据只经已验证的HTTPS传输,JSON按JWE契约处理。查看加密状态

互动与内容审核

一级评论、二级回复、本人评论、提交回执及各动态commentPreview统一新增评论顶层vipActive,表示该评论作者当前有效权益。服务端按页批量判断,Flutter据此显示VIP边框/昵称颜色/图标,不借用动态作者或登录者状态,不逐人补查;实际字段与验证范围见互动共享模型。

2026-11-10评论VIP与当前查看者计数已随908项服务器全量回归更新,接口可接入。先读互动与审核接入,包含字段模型及实际验证范围。发布成功只表示待审核;所有公开互动内容必须APPROVED。

评论与二级回复未通过时仅作者本人可从comments/mine查询;动态发布者也不能查看他人的未通过内容。公开列表、预览及分页total/hasMore只包含已通过且当前可见的记录。Post.commentCount统一按当前Bearer返回公开根/回复加本人可回显未公开记录的完整去重总数,审核通过不重复计数;提交或删除后重读动态详情,前端不本地加减,也不叠加mine.total。

接口 方法 路径
读取互动发现流 GET /api/v1/posts
读取用户已公开动态 GET /api/v1/users/{id}/posts
读取互动目录与发布限制 GET /api/v1/community/catalog
读取可选话题 GET /api/v1/topics
读取话题详情和参与统计 GET /api/v1/topics/{id}
读取评论或二级回复 GET /api/v1/posts/{postId}/comments
读取本人评论审核状态 GET /api/v1/posts/{postId}/comments/mine
提交评论或回复等待审核 POST /api/v1/posts/{postId}/comments
删除本人评论或回复 DELETE /api/v1/posts/{postId}/comments/{id}
读取音视频或私有证据 GET /api/v1/media/community-files/{id}
读取视频封面 GET /api/v1/media/community-files/{id}/poster
丢弃通用暂存文件 DELETE /api/v1/media/community-files/{id}
翻译动态正文 POST /api/v1/posts/{id}/translation
翻译评论或回复 POST /api/v1/posts/{postId}/comments/{id}/translation
提交互动内容举报 POST /api/v1/posts/{id}/reports
读取本人举报回执 GET /api/v1/me/content-reports
读取本人举报处理结果 GET /api/v1/me/content-reports/{id}

远方明信片

先读明信片接入。首信和回信都须人工审核通过后投递,数据与已接入状态分别说明。

接口 方法 路径
读取明信片首页 GET /api/v1/me/postcards/home
读取明信片收寄偏好 GET /api/v1/me/postcard-preferences
保存明信片收寄偏好 PATCH /api/v1/me/postcard-preferences
读取本人明信片信箱 GET /api/v1/me/postcards
提交待审明信片首信 POST /api/v1/postcards
领取一张已通过明信片 POST /api/v1/postcards/receive
读取私密明信片详情 GET /api/v1/postcards/{id}
拆开明信片或推进已读 POST /api/v1/postcards/{id}/open
读取已投递回信或本人审核结果 GET /api/v1/postcards/{id}/replies
提交待审明信片回信 POST /api/v1/postcards/{id}/replies
保留明信片到旅行册 PUT /api/v1/postcards/{id}/keep
取消旅行册明信片保留 DELETE /api/v1/postcards/{id}/keep
读取旅行册与真实邮戳 GET /api/v1/me/postcard-album
发起明信片聊天邀请 PUT /api/v1/postcards/{id}/chat-invitation
接受或婉拒明信片聊天邀请 PATCH /api/v1/postcards/{id}/chat-invitation
进入明信片文本会话 POST /api/v1/postcards/{id}/chat
读取本人明信片聊天列表 GET /api/v1/me/postcard-chats
读取明信片会话与未读 GET /api/v1/postcard-chats/{id}
分页读取明信片文本消息 GET /api/v1/postcard-chats/{id}/messages
发送明信片文本消息 POST /api/v1/postcard-chats/{id}/messages
推进本人聊天已读边界 PUT /api/v1/postcard-chats/{id}/read
翻译已通过私密明信片 POST /api/v1/postcards/{id}/translation
举报已通过私密明信片 POST /api/v1/postcards/{id}/reports
读取本人明信片举报回执 GET /api/v1/me/postcard-reports
读取本人明信片举报处理结果 GET /api/v1/me/postcard-reports/{id}
读取本人或已通过明信片照片 GET /api/v1/media/postcard-photos/{id}
丢弃本人未绑定明信片照片 DELETE /api/v1/media/postcard-photos/{id}

原业务接口中的用户媒体与下载授权已统一为媒体交付协议,并于2026-11-20部署:无能力头/cdn-v1/oss-v1均使用同结构,由后台决定CDN、OSS或API,业务页面直接使用返回URL,私密鉴权集中在公共加载组件。ID、保存字段和原权限保持。唯一正式部署环境仍使用dev配置;服务器及公网探针结果不代替Flutter设备验收。实际结果与待验事项见CDN协议。