API 参考

ModelFold 的 HTTP 接口分成两组：

分组	前缀	鉴权	用途
模型网关	/v1	API Key	调用图像、视频、对话模型
控制台接口	/api	登录令牌（JWT）	注册登录、账号资料、API Key、钱包、邮件

两组接口都在同一个域名下：

https://ai.modelfold.online          # 当前部署地址
https://ai.modelfold.online     # 正式域名（上线后启用）

模型网关 /v1

方法	路径	说明
GET	/v1/models	列出当前可用的模型
POST	/v1/images/generations	图像生成与编辑
POST	/v1/videos/generations	视频生成
POST	/v1/chat/completions	对话补全（OpenAI 兼容）

详见 API 网关。

控制台接口 /api

方法	路径	说明
POST	/api/auth/register	注册
POST	/api/auth/login	登录，返回 JWT
GET	/api/auth/me	当前登录用户
POST	/api/auth/logout	退出登录，吊销当前会话
GET	/api/account	用户中心概览
PUT	/api/account/profile	修改昵称
POST	/api/account/avatar	上传头像
DELETE	/api/account/avatar	删除头像
POST	/api/account/password	修改密码
GET	/api/account/sessions	登录设备列表
DELETE	/api/account/sessions/:id	退出指定设备
DELETE	/api/account/sessions	退出其它全部设备
GET	/api/keys	列出 API Key
POST	/api/keys	创建 API Key
DELETE	/api/keys/:id	吊销 API Key
GET	/api/wallet	余额与流水
POST	/api/wallet/topup	充值
GET	/api/wallet/usage	调用记录
GET	/api/mail/status	邮件通道状态
POST	/api/mail/test	发送测试邮件
POST	/api/email/verify	完成邮箱验证
POST	/api/email/resend	重发验证邮件
POST	/api/email/forgot	申请重置密码
POST	/api/email/reset	用令牌重置密码
GET	/api/health	健康检查

分页说明：目前所有列表接口都返回最近若干条记录（流水 50 条、调用记录 100 条），未提供分页参数。

统一响应结构

成功时：

{ "ok": true, "...": "各接口自有字段" }

失败时：

{ "ok": false, "error": { "type": "insufficient_credits", "message": "积分不足：需要 18，当前 5" } }

少数控制台接口的 error 是字符串而非对象（例如登录失败返回 {"ok":false,"error":"invalid_credentials"}），以各接口页面上的说明为准。

速率限制

范围	限制
/v1 网关	每 Key 每分钟 60 次
创建 API Key	每账号每分钟 30 次
注册 / 登录	每 IP 每 10 分钟 30 次
修改密码	每账号每 10 分钟 30 次
充值	每账号每分钟 10 次
邮箱相关（重发 / 找回 / 重置）	每 IP 每 10 分钟 10 次
发送测试邮件	每账号每 10 分钟 5 次

超限返回 429。响应头使用 RateLimit / RateLimit-Policy（draft-7）。

错误码

HTTP	含义
400	参数不合法（邮箱格式、密码强度、模型与端点不匹配等）
401	未认证或凭证已失效
402	余额不足
403	账号被停用
404	资源不存在
409	冲突（邮箱已注册）
429	触发速率限制
500	服务端异常
502	上游调用失败（网关场景下已自动退款）
503	上游尚未配置

健康检查

curl https://ai.modelfold.online/api/health

{ "ok": true, "db": "up" }

数据库不可用时返回 503 与 {"ok":false,"db":"down"}。