ai-paas-comparison/docs/04-API接口规范.md

# 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 响应格式

```json
// 成功
{ "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
```yaml
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
```yaml
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
```yaml
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
```yaml
description: 登录（邮箱 + 密码）
request:
  body:
    email: string (required)
    password: string (required)
response: 同上
```

### POST /api/v1/auth/refresh
```yaml
description: 刷新 Token
request:
  body:
    refresh_token: string (required)
response:
  200:
    data:
      access_token: string
      expires_in: integer
```

### GET /api/v1/auth/me
```yaml
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
```yaml
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
```yaml
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
```yaml
description: API Key 列表
auth: JWT
response:
  200:
    data:
      items:
        - id, name, key_prefix, last_used_at, status, created_at
```

### DELETE /api/v1/apikeys/{id}
```yaml
description: 删除 API Key
auth: JWT
```

---

## 5. LLM 调用接口（OpenAI 兼容，通过 NEW API）

### POST /v1/chat/completions
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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}
```yaml
description: 能力详情
auth: 公开
```

### PUT /api/v1/capabilities/{id}
```yaml
description: 更新能力（仅创建者）
auth: JWT
```

### DELETE /api/v1/capabilities/{id}
```yaml
description: 注销能力（已发布的保持在线，标记 deprecated）
auth: JWT
```

### POST /api/v1/capabilities/{id}/versions
```yaml
description: 发布新版本
auth: JWT
request:
  body:
    version: string (required)
    endpoint: string
    changelog: string
```

### POST /api/v1/capabilities/{id}/review
```yaml
description: 提交审核（管理员）
auth: JWT (admin)
request:
  body:
    action: string                 # approve/reject
    note: string
```

---

## 8. Skills 市场

### POST /api/v1/skills
```yaml
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
```yaml
description: 市场列表（公开）
auth: 公开
request:
  query:
    q: string (搜索)
    category, tags, sort (rating/popular/newest), page, page_size
```

### GET /api/v1/skills/{id}
```yaml
description: 技能详情
auth: 公开
```

### POST /api/v1/skills/{id}/purchase
```yaml
description: 购买技能
auth: JWT
request:
  body: # 无需参数，自动扣费
response:
  200:
    data:
      purchase_id: uuid
      credits_deducted: integer
      balance_after: integer
```

### GET /api/v1/skills/purchased
```yaml
description: 已购技能
auth: JWT
```

### GET /api/v1/skills/developer/dashboard
```yaml
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
```yaml
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
```yaml
description: 提现记录
auth: JWT (subscribed)
```

---

## 10. 管理后台

### GET /api/v1/admin/dashboard
```yaml
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
```yaml
description: 用户列表
auth: JWT (admin)
```

### POST /api/v1/admin/capabilities/{id}/review
```yaml
description: 能力审核
auth: JWT (admin)
```

### POST /api/v1/admin/users/{id}/suspend
```yaml
description: 封禁用户
auth: JWT (admin)
```

---

*文档结束*