qyyfw
a9e141b695
- 新增 docs/smsbao-integration.md（完整集成文档+代码示例） - 更新 PRD：注册/登录使用短信宝发送验证码 - 更新架构设计：技术栈+选型矩阵+配置说明 - 更新 API 规范：新增 /send-code 接口 - 更新 AGENTS.md：短信服务配置说明 短信宝 API: - 发送: GET https://api.smsbao.com/sms?u=&p=&m=&c= - 查询: GET http://api.smsbao.com/query?u=&p= - 签名格式: 【QihuAI】您的验证码是123456
10 KiB
10 KiB
AI PaaS 商业平台 — API 接口规范
版本: 2.0 | 日期: 2026-06-27 状态: 已修订（扁平化用户模型 + Casdoor/NEW API 集成） 规范: OpenAPI 3.0 | Base URL: https://api.aipaas.com
1. 通用约定
1.1 认证方式
| 方式 | Header | 说明 |
|---|---|---|
| JWT | Authorization: Bearer {access_token} |
Casdoor 签发，Web 前端使用 |
| API Key | Authorization: Bearer aip_{key} |
程序化调用 |
1.2 响应格式
// 成功
{ "code": 0, "message": "success", "data": { ... } }
// 分页
{ "code": 0, "message": "success", "data": { "items": [...], "total": 100, "page": 1, "page_size": 20 } }
// 错误
{ "code": 40001, "message": "Insufficient balance", "data": null }
1.3 错误码
| 错误码 | HTTP | 说明 |
|---|---|---|
| 0 | 200 | 成功 |
| 40001 | 400 | 参数错误 |
| 40101 | 401 | 未认证 |
| 40102 | 401 | API Key 无效 |
| 40301 | 403 | 权限不足（需订阅） |
| 40401 | 404 | 资源不存在 |
| 40201 | 402 | 余额不足 |
| 40302 | 403 | 未实名认证 |
| 42901 | 429 | 频率超限 |
2. 认证接口（Casdoor 代理）
POST /api/v1/auth/send-code
description: 发送手机验证码（短信宝 SMS Bao）
request:
body:
phone: string (required)
captcha_id: string (required) # 图形验证码ID
captcha_code: string (required) # 图形验证码答案
response:
200:
data:
message: "验证码已发送"
400:
code: 40001
message: "图形验证码错误"
429:
code: 42901
message: "发送太频繁，请60秒后重试"
POST /api/v1/auth/register
description: 注册（手机号 + 短信验证码）
request:
body:
phone: string (required)
code: string (required, 6位验证码)
name: string (optional, 默认 "用户_{phone后4位}")
response:
200:
data:
user_id: uuid
access_token: string (JWT, 由 Casdoor 签发)
refresh_token: string
POST /api/v1/auth/login
description: 登录（手机号 + 短信验证码）
request:
body:
phone: string (required)
code: string (required, 6位验证码)
response:
200:
data:
access_token: string
refresh_token: string
expires_in: integer
user: { id, name, phone, verified, subscribed }
POST /api/v1/auth/login/email
description: 登录（邮箱 + 密码）
request:
body:
email: string (required)
password: string (required)
response: 同上
POST /api/v1/auth/refresh
description: 刷新 Token
request:
body:
refresh_token: string (required)
response:
200:
data:
access_token: string
expires_in: integer
GET /api/v1/auth/me
description: 获取当前用户信息
auth: JWT
response:
200:
data:
id: uuid
name: string
phone: string (脱敏)
email: string
role: string
verified: boolean # 是否实名认证
subscribed: boolean # 是否订阅用户
subscription: # 订阅详情（如有）
plan: string
credits_included: integer
credits_used: integer
period_end: datetime
grace_end: datetime # 欠费保护期
3. 实名认证接口
POST /api/v1/auth/verify
description: 实名认证（调用阿里云实名认证 API）
auth: JWT
request:
body:
real_name: string (required) # 真实姓名
id_card: string (required) # 身份证号
response:
200:
data:
verified: true
message: "实名认证成功"
400:
code: 40001
message: "身份证号格式错误"
400:
code: 40303
message: "实名认证失败，姓名与身份证号不匹配"
4. API Key 管理
POST /api/v1/apikeys
description: 创建 API Key
auth: JWT
request:
body:
name: string (required)
response:
200:
data:
id: uuid
name: string
key: string # 仅此一次展示明文 aip_xxxxxxxxxxxx
key_prefix: string
created_at: datetime
GET /api/v1/apikeys
description: API Key 列表
auth: JWT
response:
200:
data:
items:
- id, name, key_prefix, last_used_at, status, created_at
DELETE /api/v1/apikeys/{id}
description: 删除 API Key
auth: JWT
5. LLM 调用接口（OpenAI 兼容，通过 NEW API）
POST /v1/chat/completions
description: Chat Completion（OpenAI 兼容格式，代理到 NEW API）
auth: JWT 或 API Key
request:
body:
model: string (required)
messages: [{ role, content }]
temperature: number (0-2, default 1)
max_tokens: integer
stream: boolean (default false)
top_p: number
response:
200:
id: string
object: "chat.completion"
model: string
choices:
- index: 0
message: { role: "assistant", content: string }
finish_reason: "stop"
usage:
prompt_tokens: integer
completion_tokens: integer
total_tokens: integer
# 流式: SSE (text/event-stream)
GET /v1/models
description: 可用模型列表（从 NEW API 获取）
auth: JWT 或 API Key
response:
200:
data:
- id: "deepseek-chat"
provider: "deepseek"
pricing: { credits_per_1k: 1.0 }
- id: "qwen-turbo"
provider: "qianwen"
pricing: { credits_per_1k: 0.8 }
- id: "ollama-qwen2.5"
provider: "ollama"
pricing: { credits_per_1k: 0.1 }
6. 计费与订阅
GET /api/v1/billing/balance
description: 查询余额
auth: JWT
response:
200:
data:
balance: integer # 当前余额 (分)
balance_display: string # "¥125.80"
plan: string
credits_included: integer
credits_used: integer
period_end: datetime
POST /api/v1/billing/subscribe
description: 订阅管理
auth: JWT
request:
body:
plan: string (required) # developer/pro/flagship
billing_cycle: string # monthly/yearly
response:
200:
data:
subscription_id: uuid
plan: string
price_cents: integer
payment_url: string # 支付链接
POST /api/v1/billing/topup
description: 充值 Token 包
auth: JWT
request:
body:
package: string (required) # 10/50/100
payment_method: string # alipay/wechat
response:
200:
data:
order_id: string
payment_url: string
GET /api/v1/billing/transactions
description: 流水查询
auth: JWT
request:
query:
page, page_size, type, start_date, end_date
response:
200:
data:
items: [{ id, type, amount, balance_after, description, trace_id, created_at }]
total, page, page_size
7. 能力注册
POST /api/v1/capabilities
description: 创建能力（需订阅用户）
auth: JWT
precondition: subscribed == true
request:
body:
name: string (required)
type: string (required) # agent/mcp/skill/llm/custom
version: string (required)
description: string
tags: array[string]
endpoint: string
response:
200:
data:
id: uuid
status: "draft"
GET /api/v1/capabilities
description: 能力列表
auth: 公开
request:
query:
type, status, tags, page, page_size
response:
200:
data:
items: [{ id, name, type, version, status, tags, invoke_count, created_at }]
GET /api/v1/capabilities/{id}
description: 能力详情
auth: 公开
PUT /api/v1/capabilities/{id}
description: 更新能力（仅创建者）
auth: JWT
DELETE /api/v1/capabilities/{id}
description: 注销能力（已发布的保持在线，标记 deprecated）
auth: JWT
POST /api/v1/capabilities/{id}/versions
description: 发布新版本
auth: JWT
request:
body:
version: string (required)
endpoint: string
changelog: string
POST /api/v1/capabilities/{id}/review
description: 提交审核（管理员）
auth: JWT (admin)
request:
body:
action: string # approve/reject
note: string
8. Skills 市场
POST /api/v1/skills
description: 发布技能（需订阅）
auth: JWT
precondition: subscribed == true
request:
body:
name: string (required)
description: string
category: string
tags: array[string]
pricing_model: string # per_call/per_token/subscription/free
price_credits: integer
endpoint: string
documentation: string
GET /api/v1/skills
description: 市场列表（公开）
auth: 公开
request:
query:
q: string (搜索)
category, tags, sort (rating/popular/newest), page, page_size
GET /api/v1/skills/{id}
description: 技能详情
auth: 公开
POST /api/v1/skills/{id}/purchase
description: 购买技能
auth: JWT
request:
body: # 无需参数，自动扣费
response:
200:
data:
purchase_id: uuid
credits_deducted: integer
balance_after: integer
GET /api/v1/skills/purchased
description: 已购技能
auth: JWT
GET /api/v1/skills/developer/dashboard
description: 开发者仪表盘
auth: JWT (subscribed)
response:
200:
data:
total_skills: integer
total_purchases: integer
total_revenue: integer
pending_payout: integer
9. 开发者提现
POST /api/v1/developer/payout
description: 申请提现
auth: JWT (subscribed)
request:
body:
amount_cents: integer (required, min 10000 = ¥100)
method: string # alipay/bank
account_info: object # 收款信息（加密传输）
GET /api/v1/developer/payouts
description: 提现记录
auth: JWT (subscribed)
10. 管理后台
GET /api/v1/admin/dashboard
description: 管理仪表盘
auth: JWT (admin)
response:
200:
data:
total_users: integer
total_subscribers: integer
total_api_calls: integer (今日)
total_revenue: integer (本月)
pending_reviews: integer
system_status: object
GET /api/v1/admin/users
description: 用户列表
auth: JWT (admin)
POST /api/v1/admin/capabilities/{id}/review
description: 能力审核
auth: JWT (admin)
POST /api/v1/admin/users/{id}/suspend
description: 封禁用户
auth: JWT (admin)
文档结束