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

// 成功
{
  "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

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

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

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

---

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

GET /api/v1/apikeys

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}

description: 删除 API Key
auth: JWT
response:
  200: { code: 0, message: "success" }

---

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

POST /v1/chat/completions

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

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

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

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

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

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

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

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}

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}

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}

description: 注销能力
auth: JWT

POST /api/v1/capabilities/{id}/versions

description: 发布新版本
auth: JWT
request:
  body:
    version: string (required)
    endpoint: string
    changelog: string

---

7. Skills 市场接口

POST /api/v1/skills

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

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

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

---

8. IM Bot 接口

POST /api/v1/im/callback/{platform}

description: 平台回调 (Webhook)
auth: 平台签名验证
request:
  body: 平台消息格式 (各平台不同)
response:
  200: 平台要求的响应格式

GET /api/v1/im/sessions

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

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

description: 用户列表
auth: JWT (admin 角色)
request:
  query:
    q: string (optional)
    status: string (optional)
    page: integer
    page_size: integer

POST /api/v1/admin/capabilities/{id}/review

description: 能力审核
auth: JWT (admin 角色)
request:
  body:
    action: string                 # approve/reject
    note: string

---

文档结束