开发文档

开发文档

API 接口文档：轻量级 AI API 中转与分销平台

API接口文档.md

API 接口文档：轻量级 AI API 中转与分销平台

版本：v0.1 日期：2026-05-11 关联文档：[PRD_API中转平台_中东非洲东南亚.md](./PRD_API中转平台_中东非洲东南亚.md)

---

1. 通用约定

Base URLs：

  • 对外模型 API：https://api.example.com/v1
  • 用户控制台 API：https://api.example.com/app
  • 管理后台 API：https://api.example.com/admin
  • 支付 webhook：https://api.example.com/webhooks

认证：

  • 模型 API 使用 Authorization: Bearer <api_key>。
  • 用户和管理后台使用 session cookie 或 JWT。
  • 管理后台必须启用 RBAC。

响应格式：

{
  "data": {},
  "error": null,
  "request_id": "req_xxx"
}

错误格式：

{
  "error": {
    "type": "insufficient_balance",
    "code": "wallet_insufficient_balance",
    "message": "Insufficient balance.",
    "param": null
  },
  "request_id": "req_xxx"
}

---

2. OpenAI-compatible API

2.1 GET /v1/models

返回当前 API Key 可用模型。

响应：

{
  "object": "list",
  "data": [
    {
      "id": "balanced-chat",
      "object": "model",
      "created": 1760000000,
      "owned_by": "platform"
    }
  ]
}

2.2 POST /v1/chat/completions

支持 OpenAI-compatible chat completions。

请求：

{
  "model": "balanced-chat",
  "messages": [
    {"role": "user", "content": "Hello"}
  ],
  "stream": false,
  "temperature": 0.7,
  "tools": []
}

响应：

{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "created": 1760000000,
  "model": "balanced-chat",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Hello!"},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 5,
    "total_tokens": 15
  }
}

Streaming：

  • 使用 text/event-stream。
  • 已开始输出后不再 fallback。
  • stream 结束后生成最终 usage 和扣费。

2.3 POST /v1/embeddings

请求：

{
  "model": "cheap-embedding",
  "input": "hello world"
}

响应遵循 OpenAI embeddings 格式。

---

3. 用户认证接口

POST /app/auth/register

请求：

{
  "email": "user@example.com",
  "password": "password",
  "country": "ID",
  "locale": "en"
}

POST /app/auth/login

请求：

{
  "email": "user@example.com",
  "password": "password"
}

POST /app/auth/logout

退出登录。

GET /app/me

返回当前用户、组织、权限、钱包摘要。

---

4. API Key 接口

GET /app/api-keys

查询 key 列表。

POST /app/api-keys

请求：

{
  "name": "Production",
  "allowed_models": ["balanced-chat", "cheap-embedding"],
  "daily_budget_usd": "20.00",
  "rpm_limit": 60,
  "tpm_limit": 100000,
  "expires_at": null
}

响应只在创建时返回明文 key：

{
  "data": {
    "id": "key_id",
    "api_key": "sk-xxxx",
    "key_prefix": "sk-abc123"
  }
}

PATCH /app/api-keys/{id}

修改名称、状态、限制。

DELETE /app/api-keys/{id}

撤销 key。

---

5. 钱包与用量接口

GET /app/wallet

响应：

{
  "data": {
    "cash_balance": "100.00",
    "promo_balance": "5.00",
    "currency": "USD",
    "low_balance_threshold": "10.00"
  }
}

GET /app/wallet/transactions

查询余额流水。

参数：

  • from
  • to
  • type
  • limit
  • cursor

GET /app/usage

参数：

  • from
  • to
  • model
  • api_key_id
  • group_by=day|model|api_key

GET /app/requests

查询请求记录 metadata。

---

6. 充值与支付接口

GET /app/payment-methods

返回当前国家可用支付方式。

POST /app/payment-orders

请求：

{
  "method": "stripe",
  "amount": "20.00",
  "currency": "USD"
}

响应：

{
  "data": {
    "order_id": "po_xxx",
    "status": "pending",
    "checkout_url": "https://checkout.stripe.com/xxx",
    "expires_at": "2026-05-11T12:00:00Z"
  }
}

GET /app/payment-orders

查询订单列表。

GET /app/payment-orders/{id}

查询订单详情。

POST /app/payment-orders/{id}/cancel

取消未支付订单。

POST /app/payment-orders/{id}/proof

提交 USDT 或银行转账付款凭证。

{
  "tx_hash": "transaction_hash_or_reference",
  "note": "optional memo"
}

---

7. 工单接口

GET /app/support/tickets

查询工单。

POST /app/support/tickets

请求：

{
  "type": "payment_issue",
  "subject": "Recharge not credited",
  "description": "I paid but balance did not update.",
  "related_payment_order_id": "po_xxx",
  "related_request_id": null
}

POST /app/support/tickets/{id}/messages

追加消息。

---

8. 管理后台接口

8.1 用户管理

  • GET /admin/users
  • GET /admin/users/{id}
  • PATCH /admin/users/{id}/status
  • GET /admin/users/{id}/wallet
  • GET /admin/users/{id}/requests

8.2 钱包管理

POST /admin/wallets/{wallet_id}/adjustments

请求：

{
  "type": "admin_credit",
  "amount_cash": "10.00",
  "amount_promo": "0.00",
  "reason": "Offline bank transfer",
  "ticket_id": "ticket_xxx"
}

要求：

  • 必须写 admin_audit_log。
  • 大额调整需要审批。

8.3 Provider 管理

  • GET /admin/provider-channels
  • POST /admin/provider-channels
  • PATCH /admin/provider-channels/{id}
  • POST /admin/provider-channels/{id}/keys
  • PATCH /admin/provider-keys/{id}
  • POST /admin/provider-channels/{id}/health-check

Provider key 明文只允许创建或轮换时提交，不允许再次读取。

8.4 模型管理

  • GET /admin/models
  • POST /admin/models
  • PATCH /admin/models/{id}
  • POST /admin/models/{id}/prices
  • GET /admin/models/{id}/price-history

8.5 订单管理

  • GET /admin/payment-orders
  • GET /admin/payment-orders/{id}
  • POST /admin/payment-orders/{id}/mark-paid
  • POST /admin/payment-orders/{id}/refund
  • POST /admin/payment-orders/{id}/chargeback

8.6 工单管理

  • GET /admin/support/tickets
  • GET /admin/support/tickets/{id}
  • PATCH /admin/support/tickets/{id}
  • POST /admin/support/tickets/{id}/messages

8.7 Status 与公告

  • GET /admin/incidents
  • POST /admin/incidents
  • PATCH /admin/incidents/{id}
  • POST /admin/incidents/{id}/updates

---

9. 支付 Webhook

POST /webhooks/stripe

要求：

  • 校验 Stripe signature。
  • 使用 Stripe event id 幂等。
  • 只接受预期事件类型。
  • 本地订单金额和币种必须匹配。

POST /webhooks/usdt

如果采用自动监听：

  • 校验链上 tx hash。
  • 校验确认数。
  • 校验收款地址和金额。
  • tx hash 幂等。

MVP 可以先不开放该接口，使用管理员审核。

---

10. 错误码

| HTTP | code | 说明 | |---|---|---| | 401 | invalid_api_key | API Key 无效 | | 403 | api_key_disabled | API Key 被禁用 | | 403 | model_not_allowed | 模型无权限 | | 402 | wallet_insufficient_balance | 余额不足 | | 429 | rate_limit_exceeded | 触发限流 | | 429 | budget_exceeded | 超出预算 | | 400 | invalid_request | 请求格式错误 | | 502 | provider_error | 上游错误 | | 503 | no_available_provider | 无可用上游 | | 500 | billing_error | 计费失败 |

---

11. 幂等要求

需要幂等的接口：

  • 支付 webhook。
  • 钱包入账。
  • 请求扣费。
  • 退款。
  • 管理员手动入账。

客户端可传：

  • Idempotency-Key

服务端必须生成：

  • request_id
  • payment_order_id
  • wallet_transaction idempotency_key

---

12. 版本策略

  • 对外模型 API 路径保持 /v1。
  • 用户和管理后台 API 可以使用内部版本头：X-API-Version。
  • breaking change 需要新 endpoint 或新版本。