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

# AI PaaS 商业平台 — API 接口规范

> 版本: 1.0 | 日期: 2026-06-27
> 规范: OpenAPI 3.0 | Base URL: https://api.aipaas.com

---

## 1. 通用约定

### 1.1 认证方式

| 方式 | Header | 说明 |
|------|--------|------|
| JWT | `Authorization: Bearer {access_token}` | 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 Status | 说明 |
|--------|------------|------|
| 0 | 200 | 成功 |
| 40001 | 400 | 请求参数错误 |
| 40101 | 401 | 未认证 |
| 40102 | 401 | API Key 无效 |
| 40301 | 403 | 权限不足 |
| 40401 | 404 | 资源不存在 |
| 40201 | 402 | Credit 余额不足 |
| 42901 | 429 | 请求频率超限 |
| 50001 | 500 | 服务内部错误 |
| 50201 | 502 | 上游服务不可用 |

---

## 2. Auth 接口

### POST /api/v1/auth/register
```yaml
description: 用户注册
request:
  body:
    email: string (required)
    password: string (required, min 8)
    name: string (required)
response:
  200:
    data:
      user_id: uuid
      email: string
      tenant_id: uuid
```

### POST /api/v1/auth/login
```yaml
description: 用户登录
request:
  body:
    email: string (required)
    password: string (required)
response:
  200:
    data:
      access_token: string (JWT, 1h)
      refresh_token: string (JWT, 7d)
      expires_in: integer (seconds)
      user:
        id: uuid
        name: string
        email: string
        role: string
        tenant_id: uuid
```

### 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
      email: string
      role: string
      tenant_id: uuid
      tenant:
        name: string
        plan: string
        credit_balance: integer
```

---

## 3. 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            # 仅此一次展示明文
      key_prefix: string     # aip_xxxx
      created_at: datetime
```

### GET /api/v1/apikeys
```yaml
description: API Key 列表
auth: JWT
response:
  200:
    data:
      items:
        - id: uuid
          name: string
          key_prefix: string
          last_used_at: datetime
          status: string
          created_at: datetime
```

### DELETE /api/v1/apikeys/{id}
```yaml
description: 删除 API Key
auth: JWT
response:
  200: { code: 0, message: "success" }
```

---

## 4. LLM 调用接口（OpenAI 兼容）

### POST /v1/chat/completions
```yaml
description: Chat Completion (OpenAI 兼容格式)
auth: API Key 或 JWT
request:
  body:
    model: string (required)       # deepseek-chat, qwen-turbo, etc.
    messages:
      - role: string               # system/user/assistant
        content: string
    temperature: number (optional, 0-2, default 1)
    max_tokens: integer (optional)
    stream: boolean (optional, default false)
    top_p: number (optional)
    stop: string | array (optional)
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)
    # Content-Type: text/event-stream
    # data: {"id":"...","choices":[{"delta":{"content":"token"}}]}
    # data: [DONE]
```

### GET /v1/models
```yaml
description: 可用模型列表
auth: API Key 或 JWT
response:
  200:
    data:
      - id: "deepseek-chat"
        object: "model"
        provider: "deepseek"
        pricing:
          credits_per_1k: 1.0
      - id: "qwen-turbo"
        object: "model"
        provider: "qianwen"
        pricing:
          credits_per_1k: 0.8
```

---

## 5. Billing 接口

### GET /api/v1/billing/balance
```yaml
description: 查询 Credit 余额
auth: JWT
response:
  200:
    data:
      balance: integer         # 当前余额 (毫 Credit)
      balance_display: number  # 显示余额 (Credit)
      plan: string
      credits_included: integer
      credits_used: integer
      period_end: datetime
```

### POST /api/v1/billing/topup
```yaml
description: 充值
auth: JWT
request:
  body:
    amount: integer (required)     # 充值金额 (分)
    payment_method: string         # alipay/wechat
response:
  200:
    data:
      order_id: string
      payment_url: string          # 支付链接
```

### GET /api/v1/billing/transactions
```yaml
description: Credit 流水查询
auth: JWT
request:
  query:
    page: integer (default 1)
    page_size: integer (default 20)
    type: string (optional)        # usage/topup/subscription
    start_date: date (optional)
    end_date: date (optional)
response:
  200:
    data:
      items:
        - id: uuid
          type: string
          amount: integer
          balance_after: integer
          description: string
          trace_id: string
          created_at: datetime
      total: integer
      page: integer
      page_size: integer
```

### POST /api/v1/billing/subscribe
```yaml
description: 订阅管理
auth: JWT
request:
  body:
    plan: string (required)     # pro/team
    billing_cycle: string       # monthly/yearly
response:
  200:
    data:
      subscription_id: uuid
      plan: string
      price_cents: integer
      credits_included: integer
      period_start: datetime
      period_end: datetime
```

---

## 6. Capability Registry 接口

### POST /api/v1/capabilities
```yaml
description: 注册新能力
auth: JWT
request:
  body:
    name: string (required)
    type: string (required)       # agent/mcp/skill/llm/custom
    version: string (required)    # SemVer
    description: string
    tags: array[string]
    endpoint: string
    protocol: string              # rest/grpc/websocket
    pricing_config: object
response:
  200:
    data:
      id: uuid
      status: "draft"
```

### GET /api/v1/capabilities
```yaml
description: 能力列表
auth: JWT 或 API Key
request:
  query:
    type: string (optional)
    status: string (optional)
    tags: string (optional)       # 逗号分隔
    page: integer
    page_size: integer
response:
  200:
    data:
      items:
        - id: uuid
          name: string
          type: string
          version: string
          status: string
          tags: array[string]
          invoke_count: integer
          created_at: datetime
```

### GET /api/v1/capabilities/{id}
```yaml
description: 能力详情
auth: JWT 或 API Key
response:
  200:
    data:
      id: uuid
      name: string
      type: string
      version: string
      description: string
      tags: array[string]
      endpoint: string
      protocol: string
      pricing_config: object
      status: string
      invoke_count: integer
      created_at: datetime
```

### PUT /api/v1/capabilities/{id}
```yaml
description: 更新能力
auth: JWT
request:
  body:
    name: string (optional)
    description: string (optional)
    tags: array[string] (optional)
    endpoint: string (optional)
    pricing_config: object (optional)
```

### DELETE /api/v1/capabilities/{id}
```yaml
description: 注销能力
auth: JWT
```

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

---

## 7. Skills 市场接口

### POST /api/v1/skills
```yaml
description: 发布技能
auth: JWT
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
response:
  200:
    data:
      id: uuid
```

### GET /api/v1/skills
```yaml
description: 市场列表
auth: 公开
request:
  query:
    q: string (optional)          # 搜索关键词
    category: string (optional)
    tags: string (optional)
    sort: string                  # rating/popular/newest
    page: integer
    page_size: integer
response:
  200:
    data:
      items:
        - id: uuid
          name: string
          description: string
          category: string
          pricing_model: string
          price_credits: integer
          rating: number
          purchase_count: integer
          developer:
            name: string
```

### 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
response:
  200:
    data:
      items:
        - skill_id: uuid
          name: string
          purchased_at: datetime
```

---

## 8. IM Bot 接口

### POST /api/v1/im/callback/{platform}
```yaml
description: 平台回调 (Webhook)
auth: 平台签名验证
request:
  body: 平台消息格式 (各平台不同)
response:
  200: 平台要求的响应格式
```

### GET /api/v1/im/sessions
```yaml
description: 会话列表
auth: JWT
response:
  200:
    data:
      items:
        - id: uuid
          platform: string
          user_identifier: string
          user_name: string
          model: string
          last_active_at: datetime
```

---

## 9. Admin 接口

### GET /api/v1/admin/dashboard
```yaml
description: 管理仪表盘
auth: JWT (admin 角色)
response:
  200:
    data:
      total_users: integer
      total_tenants: integer
      total_api_calls: integer (今日)
      total_revenue: integer (本月)
      system_status: object
```

### GET /api/v1/admin/users
```yaml
description: 用户列表
auth: JWT (admin 角色)
request:
  query:
    q: string (optional)
    status: string (optional)
    page: integer
    page_size: integer
```

### POST /api/v1/admin/capabilities/{id}/review
```yaml
description: 能力审核
auth: JWT (admin 角色)
request:
  body:
    action: string                 # approve/reject
    note: string
```

---

*文档结束*