taiji-pda-v0/docs/BACKEND_API_SPECIFICATION_V2.md

Taiji AI Platform 后端接口规范 (RESTful API)

📌 API文档版本

• 版本: 2.0
• 更新时间: 2025-01-15
• 后端框架: FastAPI
• 数据库: PostgreSQL + Redis

🔑 认证说明

认证方式

所有需要认证的接口（除 /api/auth/login 外）都需要在请求头中包含以下之一：

方式1: Bearer Token

Authorization: Bearer <jwt_token>

方式2: API Key

X-API-Key: <api_key>

Token类型

Token类型	用途	过期时间
access_token	短期访问令牌	1440分钟
refresh_token	刷新访问令牌	7天

响应格式

所有API响应采用统一格式：

{
  "success": true,
  "data": { /* 响应数据 */ },
  "message": "操作成功",
  "error": null
}

错误响应:

{
  "success": false,
  "data": null,
  "message": null,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "请求参数错误"
  }
}

---

🔐 认证模块 API

基础路径: /api/auth

1. 用户登录

端点: POST /api/auth/login

权限: 无需认证

请求体:

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

参数说明:

参数	类型	必需	说明
email	string	✅	用户邮箱
password	string	✅	用户密码
role	enum	❌	登录角色: user/channel/admin/provider (默认: user)

响应 (200):

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "refresh_token_string",
    "user": {
      "id": "uuid",
      "email": "user@example.com",
      "name": "User Name",
      "role": "user",
      "subscription_tier": "free",
      "balance": 1000.00
    }
  }
}

---

2. 用户登出

端点: POST /api/auth/logout

权限: ✅ 需要认证

请求体: 空

响应 (200):

{
  "success": true,
  "message": "登出成功"
}

---

3. 刷新Token

端点: POST /api/auth/refresh

权限: ✅ 需要认证

请求体: 空

响应 (200):

{
  "success": true,
  "data": {
    "token": "new_jwt_token",
    "refreshToken": "new_refresh_token"
  }
}

---

4. 修改密码

端点: PUT /api/auth/password

权限: ✅ 需要认证

请求体:

{
  "old_password": "oldpass123",
  "new_password": "newpass456"
}

响应 (200):

{
  "success": true,
  "message": "密码修改成功"
}

---

5. 获取API密钥信息

端点: GET /api/auth/keys/info

权限: ✅ 需要认证

请求体: 空

响应 (200):

{
  "success": true,
  "data": {
    "api_key": "sk_live_1234567890abcdefghijklmnopqrstuvwxyz",
    "created_at": "2025-01-01T00:00:00Z",
    "last_used": "2025-01-15T12:30:00Z"
  }
}

---

6. 重新生成API密钥

端点: POST /api/auth/keys/regenerate

权限: ✅ 需要认证

请求体: 空

响应 (200):

{
  "success": true,
  "data": {
    "api_key": "sk_live_new_key_string",
    "message": "API密钥已重新生成，旧密钥将失效"
  }
}

---

👤 用户侧平台 API

基础路径: /api/user

1. 获取仪表板统计

端点: GET /api/user/dashboard/stats

权限: ✅ 需要认证

查询参数: 无

响应 (200):

{
  "success": true,
  "data": {
    "total_agents": 12,
    "active_agents": 8,
    "total_executions": 2500,
    "success_rate": 98.5,
    "monthly_cost": 1250.50,
    "balance": 5000.00,
    "eu_balance": 50000,
    "daily_active_users": 15
  }
}

---

2. 获取Agent活动数据

端点: GET /api/user/agents/activity?period={period}

权限: ✅ 需要认证

查询参数:

参数	类型	必需	说明	可选值
period	string	❌	时间周期	7d / 30d / 90d (默认: 7d)

响应 (200):

{
  "success": true,
  "data": {
    "period": "7d",
    "data": [
      {
        "date": "2025-01-15",
        "executions": 120,
        "success": 118,
        "failed": 2,
        "cost": 180.50
      }
    ]
  }
}

---

3. 选择网关类型

端点: POST /api/user/gateway/select

权限: ✅ 需要认证

请求体:

{
  "gatewayType": "MCP"
}

参数说明:

参数	类型	必需	说明	可选值
gatewayType	string	✅	网关类型	MCP / A2A / API

响应 (200):

{
  "success": true,
  "data": {
    "gateway_type": "MCP",
    "endpoint": "ws://api.taiji-ai.com/mcp",
    "message": "网关选择已保存"
  }
}

---

4. 创建网关API

端点: POST /api/user/gateway/api/create

权限: ✅ 需要认证

请求体:

{
  "name": "My Custom API",
  "method": "json",
  "content": "{\"endpoint\": \"https://api.example.com\", \"auth\": \"bearer\"}"
}

参数说明:

参数	类型	必需	说明
name	string	✅	API名称
method	enum	✅	方式：json/url
content	string	✅	API配置内容

响应 (201):

{
  "success": true,
  "data": {
    "id": "gateway_api_uuid",
    "name": "My Custom API",
    "method": "json",
    "created_at": "2025-01-15T12:00:00Z"
  }
}

---

5. 获取网关API列表

端点: GET /api/user/gateway/apis

权限: ✅ 需要认证

查询参数: 无

响应 (200):

{
  "success": true,
  "data": {
    "apis": [
      {
        "id": "uuid1",
        "name": "API 1",
        "method": "json",
        "status": "active",
        "created_at": "2025-01-15T12:00:00Z"
      }
    ],
    "total": 1
  }
}

---

6. 获取网关监控数据

端点: GET /api/user/gateway/monitoring

权限: ✅ 需要认证

查询参数: 无

响应 (200):

{
  "success": true,
  "data": {
    "status": "healthy",
    "uptime": 99.98,
    "requests_per_minute": 1250,
    "average_latency_ms": 125,
    "error_rate": 0.02,
    "active_connections": 42
  }
}

---

7. 生成工具

端点: POST /api/user/tools/generate

权限: ✅ 需要认证

请求体:

{
  "name": "Weather Tool",
  "description": "获取天气信息",
  "frameworkTemplate": "openapi",
  "gateway": "MCP",
  "agentCount": 2,
  "cpu": 1,
  "memory": 2,
  "maxScale": 5,
  "model": "gpt-4o-mini"
}

响应 (201):

{
  "success": true,
  "data": {
    "tool_id": "tool_uuid",
    "name": "Weather Tool",
    "status": "ready",
    "endpoint": "https://api.taiji-ai.com/tools/weather",
    "generated_at": "2025-01-15T12:00:00Z"
  }
}

---

8. 创建数据模板

端点: POST /api/user/data-templates/create

权限: ✅ 需要认证

请求体 (JSON API):

{
  "name": "User API Template",
  "type": "json_api",
  "config": {
    "endpoint": "https://api.example.com/users",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer token"
    },
    "params": {}
  }
}

请求体 (Cloud Storage):

{
  "name": "S3 Storage Config",
  "type": "cloud_storage",
  "config": {
    "provider": "s3",
    "bucket": "my-bucket",
    "region": "us-east-1",
    "credentials": {
      "access_key": "key",
      "secret_key": "secret"
    }
  }
}

响应 (201):

{
  "success": true,
  "data": {
    "template_id": "template_uuid",
    "name": "User API Template",
    "type": "json_api",
    "status": "active"
  }
}

---

9. 获取平台Agent列表

端点: GET /api/user/agents/platform?page={page}&limit={limit}

权限: ✅ 需要认证

查询参数:

参数	类型	必需	默认值	说明
page	int	❌	1	分页页码
limit	int	❌	20	每页条数
category	string	❌		按分类过滤

响应 (200):

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "agent_uuid",
        "name": "Data Analyzer",
        "type": "platform",
        "description": "数据分析Agent",
        "category": "analytics",
        "version": "1.0.0",
        "status": "available",
        "capabilities": ["数据处理", "图表生成"],
        "required_resources": {
          "cpu": 1,
          "memory": 2,
          "min_instances": 1,
          "max_instances": 10
        },
        "cost_per_execution": 0.10
      }
    ],
    "total": 45,
    "page": 1,
    "limit": 20
  }
}

---

10. 部署Agent

端点: POST /api/user/agents/deploy

权限: ✅ 需要认证

请求体:

{
  "agentId": "agent_uuid",
  "instances": 2,
  "model": "gpt-4o-mini",
  "gateway": "MCP",
  "config": {
    "timeout": 30,
    "retries": 3,
    "temperature": 0.7
  }
}

参数说明:

参数	类型	必需	说明
agentId	string	✅	Agent ID
instances	int	✅	实例数 (1-100)
model	string	✅	使用的模型
gateway	enum	✅	网关: MCP/A2A/API
config	object	❌	自定义配置

响应 (201):

{
  "success": true,
  "data": {
    "deployment_id": "deploy_uuid",
    "agent_id": "agent_uuid",
    "status": "deploying",
    "instances": 2,
    "endpoint": "https://api.taiji-ai.com/agents/deploy_uuid",
    "created_at": "2025-01-15T12:00:00Z"
  }
}

---

11. 创建工作流

端点: POST /api/user/workflows/create

权限: ✅ 需要认证

请求体:

{
  "name": "Data Pipeline",
  "description": "数据处理流程",
  "gateway": "A2A",
  "nodes": [
    {
      "agentId": "agent_uuid_1",
      "agentType": "platform",
      "agentName": "Data Collector",
      "order": 1
    },
    {
      "agentId": "agent_uuid_2",
      "agentType": "platform",
      "agentName": "Data Processor",
      "order": 2
    },
    {
      "agentId": "agent_uuid_3",
      "agentType": "custom",
      "agentName": "Report Generator",
      "order": 3
    }
  ]
}

参数说明:

参数	类型	必需	说明
name	string	✅	工作流名称
description	string	❌	工作流描述
gateway	enum	✅	网关类型
nodes	array	✅	Agent节点 (最多3个)

响应 (201):

{
  "success": true,
  "data": {
    "workflow_id": "workflow_uuid",
    "name": "Data Pipeline",
    "status": "created",
    "nodes_count": 3,
    "created_at": "2025-01-15T12:00:00Z"
  }
}

---

12. 获取余额信息

端点: GET /api/user/billing/balance

权限: ✅ 需要认证

查询参数: 无

响应 (200):

{
  "success": true,
  "data": {
    "balance": 5000.00,
    "eu_balance": 50000,
    "currency": "CNY",
    "subscription_tier": "pro",
    "monthly_limit": 10000.00,
    "monthly_spent": 1250.50,
    "monthly_remaining": 8749.50
  }
}

---

13. 充值余额

端点: POST /api/user/billing/recharge

权限: ✅ 需要认证

请求体:

{
  "amount": 1000.00,
  "paymentMethod": "alipay"
}

参数说明:

参数	类型	必需	说明	可选值
amount	float	✅	充值金额	>= 10.00
paymentMethod	enum	✅	支付方式	alipay / wechat / card

响应 (201):

{
  "success": true,
  "data": {
    "order_id": "order_uuid",
    "amount": 1000.00,
    "payment_method": "alipay",
    "status": "pending",
    "pay_url": "https://payment.taiji-ai.com/pay?order_id=order_uuid",
    "expires_at": "2025-01-15T13:00:00Z"
  }
}

---

14. 获取计费历史

端点: GET /api/user/billing/history?startTime={startTime}&endTime={endTime}&export={export}

权限: ✅ 需要认证

查询参数:

参数	类型	必需	说明
startTime	string	✅	开始时间 (ISO8601)
endTime	string	✅	结束时间 (ISO8601)
customerName	string	❌	客户名称 (模糊搜索)
minCalls	int	❌	最少调用次数
maxCalls	int	❌	最多调用次数
export	enum	❌	导出格式 (excel/csv/pdf)
page	int	❌	分页页码 (默认: 1)
pageSize	int	❌	每页条数 (默认: 20)

响应 (200):

{
  "success": true,
  "data": {
    "records": [
      {
        "timestamp": "2025-01-15T10:30:00Z",
        "agent_type": "data-analyzer",
        "operation": "execution",
        "calls": 5,
        "cost": 50.00,
        "eu": 500,
        "status": "success"
      }
    ],
    "total": 150,
    "page": 1,
    "pageSize": 20,
    "export_url": "https://files.taiji-ai.com/billing_2025_01.xlsx"
  }
}

---

🤝 渠道合作伙伴 API

基础路径: /api/channel

1. 获取租户列表

端点: GET /api/channel/tenants?page={page}&limit={limit}&status={status}

权限: ✅ 需要认证 (Channel Admin)

查询参数:

参数	类型	必需	说明
page	int	❌	分页页码
limit	int	❌	每页条数
status	enum	❌	active / inactive / suspended
search	string	❌	搜索条件

响应 (200):

{
  "success": true,
  "data": {
    "tenants": [
      {
        "id": "tenant_uuid",
        "name": "Company A",
        "email": "admin@company-a.com",
        "subscription_tier": "pro",
        "discount": 10.0,
        "balance": 2000.00,
        "credit_limit": 5000.00,
        "status": "active",
        "allocated_agents": 20,
        "used_agents": 8,
        "allocated_models": ["gpt-4", "gpt-4o-mini"],
        "created_at": "2025-01-01T00:00:00Z"
      }
    ],
    "total": 45,
    "page": 1,
    "limit": 20
  }
}

---

2. 创建租户

端点: POST /api/channel/tenants/create

权限: ✅ 需要认证 (Channel Admin)

请求体:

{
  "name": "Company B",
  "email": "admin@company-b.com",
  "systemRole": "admin",
  "subscriptionTier": "free",
  "initialBalance": 500.00,
  "discount": 5.0
}

参数说明:

参数	类型	必需	说明	可选值
name	string	✅	企业名称
email	string	✅	管理员邮箱
systemRole	enum	✅	系统权限	admin / billing-admin / operations-admin
subscriptionTier	enum	❌	订阅级别 (默认:free)	free / pro / enterprise
initialBalance	float	❌	初始余额	>= 0
discount	float	❌	折扣率 (%)	0-100

响应 (201):

{
  "success": true,
  "data": {
    "tenant_id": "tenant_uuid",
    "name": "Company B",
    "email": "admin@company-b.com",
    "subscription_tier": "free",
    "initial_password": "temp_password_123",
    "message": "租户已创建，请妥善保管临时密码",
    "created_at": "2025-01-15T12:00:00Z"
  }
}

---

3. 分配租户资源

端点: PUT /api/channel/tenants/{tenantId}/resources

权限: ✅ 需要认证 (Channel Admin)

URL参数:

参数	说明
tenantId	租户UUID

请求体:

{
  "agents": [
    {
      "agentId": "agent_uuid_1",
      "quantity": 10
    },
    {
      "agentId": "agent_uuid_2",
      "quantity": 5
    }
  ],
  "models": ["gpt-4", "gpt-4o-mini"],
  "rpm": 1000,
  "tpm": 100000
}

参数说明:

参数	类型	必需	说明
agents	array	❌	Agent资源列表
models	array	❌	可用模型列表
rpm	int	❌	每分钟请求限制
tpm	int	❌	每分钟令牌限制

响应 (200):

{
  "success": true,
  "data": {
    "tenant_id": "tenant_uuid",
    "allocated_agents": 15,
    "allocated_models": ["gpt-4", "gpt-4o-mini"],
    "rpm": 1000,
    "tpm": 100000,
    "updated_at": "2025-01-15T12:00:00Z"
  }
}

---

4. 更新租户计费设置

端点: PUT /api/channel/tenants/{tenantId}/billing

权限: ✅ 需要认证 (Channel Admin)

URL参数:

参数	说明
tenantId	租户UUID

请求体:

{
  "subscriptionTier": "pro",
  "discount": 15.0,
  "monthlyLimit": 10000.00
}

参数说明:

参数	类型	必需	说明
subscriptionTier	enum	❌	free / pro / enterprise
discount	float	❌	折扣率 (%)
monthlyLimit	float	❌	月度消费上限

响应 (200):

{
  "success": true,
  "data": {
    "tenant_id": "tenant_uuid",
    "subscription_tier": "pro",
    "discount": 15.0,
    "monthly_limit": 10000.00,
    "updated_at": "2025-01-15T12:00:00Z"
  }
}

---

5. 为租户充值

端点: POST /api/channel/tenants/{tenantId}/recharge

权限: ✅ 需要认证 (Channel Admin)

URL参数:

参数	说明
tenantId	租户UUID

请求体:

{
  "amount": 500.00,
  "remark": "月度充值"
}

参数说明:

参数	类型	必需	说明
amount	float	✅	充值金额
remark	string	❌	充值备注

响应 (201):

{
  "success": true,
  "data": {
    "recharge_id": "recharge_uuid",
    "tenant_id": "tenant_uuid",
    "amount": 500.00,
    "new_balance": 2500.00,
    "created_at": "2025-01-15T12:00:00Z"
  }
}

---

6. 设置租户授信额度

端点: PUT /api/channel/tenants/{tenantId}/credit

权限: ✅ 需要认证 (Channel Admin)

URL参数:

参数	说明
tenantId	租户UUID

请求体:

{
  "creditLimit": 10000.00,
  "reason": "年度合约"
}

参数说明:

参数	类型	必需	说明
creditLimit	float	✅	授信额度
reason	string	❌	授信原因

响应 (200):

{
  "success": true,
  "data": {
    "tenant_id": "tenant_uuid",
    "credit_limit": 10000.00,
    "updated_at": "2025-01-15T12:00:00Z"
  }
}

---

7. 申请资源

端点: POST /api/channel/resources/apply

权限: ✅ 需要认证 (Channel Admin)

请求体 (申请模型):

{
  "type": "model",
  "modelName": "gpt-4",
  "rpm": 2000,
  "tpm": 200000,
  "reason": "业务增长需要更高配额"
}

请求体 (申请Agent):

{
  "type": "agent",
  "agentType": "data-analyzer",
  "quantity": 20,
  "reason": "扩展Agent部署"
}

参数说明:

参数	类型	必需	说明
type	enum	✅	model / agent
modelName	string	⚠️	模型名称 (type=model时必需)
rpm	int	⚠️	RPM (type=model时)
tpm	int	⚠️	TPM (type=model时)
agentType	string	⚠️	Agent类型 (type=agent时必需)
quantity	int	⚠️	数量 (type=agent时必需)
reason	string	✅	申请原因

响应 (201):

{
  "success": true,
  "data": {
    "application_id": "app_uuid",
    "type": "model",
    "status": "pending",
    "created_at": "2025-01-15T12:00:00Z"
  }
}

---

8. 获取渠道计费统计

端点: GET /api/channel/billing/stats?startTime={startTime}&endTime={endTime}&export={export}

权限: ✅ 需要认证 (Channel Admin)

查询参数:

参数	类型	必需	说明
startTime	string	✅	开始时间 (ISO8601)
endTime	string	✅	结束时间 (ISO8601)
tenantName	string	❌	租户名称 (模糊搜索)
minCalls	int	❌	最少调用次数
maxCalls	int	❌	最多调用次数
export	enum	❌	导出格式 (excel/csv/pdf)

响应 (200):

{
  "success": true,
  "data": {
    "summary": {
      "total_cost": 15000.00,
      "total_calls": 25000,
      "total_eu": 250000,
      "active_tenants": 20
    },
    "by_tenant": [
      {
        "tenant_id": "tenant_uuid",
        "tenant_name": "Company A",
        "calls": 5000,
        "cost": 5000.00,
        "eu": 50000
      }
    ],
    "export_url": "https://files.taiji-ai.com/channel_billing_2025_01.xlsx"
  }
}

---

🔑 超级管理员 API

基础路径: /api/admin

1. 获取平台统计

端点: GET /api/admin/dashboard/stats

权限: ✅ 需要认证 (Super Admin)

查询参数: 无

响应 (200):

{
  "success": true,
  "data": {
    "total_users": 1500,
    "total_channels": 50,
    "total_agents": 200,
    "total_executions": 150000,
    "monthly_revenue": 75000.00,
    "platform_status": "healthy",
    "active_agents": 180,
    "average_success_rate": 98.5,
    "peak_qps": 2500,
    "storage_usage": "2.5TB / 10TB"
  }
}

---

2. 创建管理员

端点: POST /api/admin/admins/create

权限: ✅ 需要认证 (Super Admin)

请求体:

{
  "name": "Admin Name",
  "email": "admin@example.com",
  "password": "initial_password",
  "role": "billing"
}

参数说明:

参数	类型	必需	说明	可选值
name	string	✅	管理员名称
email	string	✅	邮箱地址
password	string	✅	初始密码
role	enum	✅	角色	billing / operations

响应 (201):

{
  "success": true,
  "data": {
    "admin_id": "admin_uuid",
    "name": "Admin Name",
    "email": "admin@example.com",
    "role": "billing",
    "created_at": "2025-01-15T12:00:00Z"
  }
}

---

3. 获取渠道列表

端点: GET /api/admin/channels?page={page}&limit={limit}&status={status}

权限: ✅ 需要认证 (Super Admin)

查询参数:

参数	类型	必需	说明
page	int	❌	分页页码
limit	int	❌	每页条数
status	enum	❌	active / inactive

响应 (200):

{
  "success": true,
  "data": {
    "channels": [
      {
        "id": "channel_uuid",
        "name": "Partner Channel A",
        "contact_email": "contact@channel-a.com",
        "commission_rate": 10.0,
        "status": "active",
        "tenants_count": 25,
        "monthly_revenue": 10000.00,
        "created_at": "2025-01-01T00:00:00Z"
      }
    ],
    "total": 50,
    "page": 1,
    "limit": 20
  }
}

---

4. 创建渠道

端点: POST /api/admin/channels/create

权限: ✅ 需要认证 (Super Admin)

请求体:

{
  "name": "New Channel",
  "email": "contact@channel.com",
  "commissionRate": 12.0,
  "initialCredit": 50000.00
}

参数说明:

参数	类型	必需	说明
name	string	✅	渠道名称
email	string	✅	联系邮箱
commissionRate	float	✅	手续费率 (%)
initialCredit	float	❌	初始信用额度

响应 (201):

{
  "success": true,
  "data": {
    "channel_id": "channel_uuid",
    "name": "New Channel",
    "email": "contact@channel.com",
    "commission_rate": 12.0,
    "created_at": "2025-01-15T12:00:00Z"
  }
}

---

5. 更新渠道信息

端点: PUT /api/admin/channels/{channelId}

权限: ✅ 需要认证 (Super Admin)

URL参数:

参数	说明
channelId	渠道UUID

请求体:

{
  "name": "Updated Channel Name",
  "email": "new-email@channel.com",
  "commissionRate": 15.0,
  "status": "active"
}

响应 (200):

{
  "success": true,
  "data": {
    "channel_id": "channel_uuid",
    "name": "Updated Channel Name",
    "updated_at": "2025-01-15T12:00:00Z"
  }
}

---

6. 删除渠道

端点: DELETE /api/admin/channels/{channelId}

权限: ✅ 需要认证 (Super Admin)

URL参数:

参数	说明
channelId	渠道UUID

响应 (200):

{
  "success": true,
  "message": "渠道已删除（软删除）",
  "data": {
    "channel_id": "channel_uuid",
    "deleted_at": "2025-01-15T12:00:00Z"
  }
}

---

7. 统一管理渠道资源

端点: PUT /api/admin/channels/{channelId}/resources

权限: ✅ 需要认证 (Super Admin)

URL参数:

参数	说明
channelId	渠道UUID

请求体:

{
  "models": ["gpt-4", "gpt-4o-mini", "claude-3"],
  "agents": [
    {
      "agentId": "agent_uuid_1",
      "quantity": 100
    },
    {
      "agentId": "agent_uuid_2",
      "quantity": 50
    }
  ],
  "customAgentResources": {
    "cpu": 200,
    "memory": 500
  },
  "channelCredit": 100000.00
}

参数说明:

参数	类型	必需	说明
models	array	❌	可用模型列表
agents	array	❌	Agent资源列表
customAgentResources	object	❌	自定义Agent资源
channelCredit	float	❌	渠道信用额度

响应 (200):

{
  "success": true,
  "data": {
    "channel_id": "channel_uuid",
    "allocated_models": ["gpt-4", "gpt-4o-mini", "claude-3"],
    "allocated_agents_count": 150,
    "custom_resources": {
      "cpu": 200,
      "memory": 500
    },
    "channel_credit": 100000.00,
    "updated_at": "2025-01-15T12:00:00Z"
  }
}

---

8. 获取所有申请

端点: GET /api/admin/channels/applications?status={status}&type={type}

权限: ✅ 需要认证 (Super Admin)

查询参数:

参数	类型	必需	说明
status	enum	❌	pending / approved / rejected
type	enum	❌	model / agent
page	int	❌	分页页码
limit	int	❌	每页条数

响应 (200):

{
  "success": true,
  "data": {
    "applications": [
      {
        "id": "app_uuid",
        "channel_id": "channel_uuid",
        "channel_name": "Partner Channel",
        "type": "model",
        "requested_resource": "gpt-4",
        "reason": "业务增长需要",
        "status": "pending",
        "created_at": "2025-01-15T10:00:00Z"
      }
    ],
    "total": 25,
    "page": 1,
    "limit": 20
  }
}

---

9. 审批申请

端点: PUT /api/admin/channels/applications/{appId}/review

权限: ✅ 需要认证 (Super Admin)

URL参数:

参数	说明
appId	申请UUID

请求体:

{
  "action": "approve",
  "reason": "已批准"
}

参数说明:

参数	类型	必需	说明	可选值
action	enum	✅	批准/拒绝	approve / reject
reason	string	✅	审批原因

响应 (200):

{
  "success": true,
  "data": {
    "application_id": "app_uuid",
    "status": "approved",
    "reviewed_at": "2025-01-15T12:00:00Z"
  }
}

---

10. 获取模型供应商

端点: GET /api/admin/resources/models

权限: ✅ 需要认证 (Super Admin)

查询参数: 无

响应 (200):

{
  "success": true,
  "data": {
    "providers": [
      {
        "id": "provider_uuid",
        "name": "OpenAI",
        "models": [
          {
            "id": "model_uuid",
            "name": "gpt-4",
            "type": "chat",
            "pricing": {
              "input": 0.03,
              "output": 0.06
            }
          },
          {
            "id": "model_uuid2",
            "name": "gpt-4o-mini",
            "type": "chat",
            "pricing": {
              "input": 0.00015,
              "output": 0.0006
            }
          }
        ]
      }
    ]
  }
}

---

11. 获取Agent资源列表

端点: GET /api/admin/resources/agents?type={type}&status={status}

权限: ✅ 需要认证 (Super Admin)

查询参数:

参数	类型	必需	说明
type	enum	❌	platform / custom
status	enum	❌	active / inactive

响应 (200):

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "agent_uuid",
        "name": "Data Analyzer",
        "type": "platform",
        "status": "active",
        "owner": "System",
        "total_instances": 500,
        "active_instances": 450,
        "monthly_executions": 50000,
        "success_rate": 99.2,
        "cost_per_call": 0.10
      }
    ],
    "total": 45
  }
}

---

12. 删除Agent资源

端点: DELETE /api/admin/resources/agents/{agentId}

权限: ✅ 需要认证 (Super Admin)

URL参数:

参数	说明
agentId	Agent UUID

响应 (200):

{
  "success": true,
  "message": "Agent资源已删除（软删除）",
  "data": {
    "agent_id": "agent_uuid",
    "deleted_at": "2025-01-15T12:00:00Z"
  }
}

---

13. 监控Agent健康

端点: GET /api/admin/monitoring/agents?status={status}

权限: ✅ 需要认证 (Super Admin)

查询参数:

参数	类型	必需	说明
status	enum	❌	healthy / warning / error

响应 (200):

{
  "success": true,
  "data": {
    "agents_status": [
      {
        "agent_id": "agent_uuid",
        "agent_name": "Data Analyzer",
        "status": "healthy",
        "uptime": 99.98,
        "cpu_usage": 45,
        "memory_usage": 60,
        "active_instances": 45,
        "last_check": "2025-01-15T12:00:00Z"
      }
    ],
    "overall_status": "healthy",
    "healthy_count": 40,
    "warning_count": 3,
    "error_count": 2
  }
}

---

14. 获取计费总览

端点: GET /api/admin/billing/overview?period={period}

权限: ✅ 需要认证 (Super Admin)

查询参数:

参数	类型	必需	说明
period	enum	❌	day / week / month / year

响应 (200):

{
  "success": true,
  "data": {
    "period": "month",
    "overview": {
      "total_revenue": 100000.00,
      "total_cost": 45000.00,
      "profit": 55000.00,
      "profit_margin": 55.0
    },
    "by_channel": {
      "total_channels": 50,
      "top_channels": [
        {
          "channel_id": "channel_uuid",
          "channel_name": "Top Channel",
          "revenue": 15000.00,
          "cost": 6000.00,
          "commission": 1500.00
        }
      ]
    },
    "by_agent": {
      "total_agents": 200,
      "top_agents": [
        {
          "agent_id": "agent_uuid",
          "agent_name": "Data Analyzer",
          "executions": 10000,
          "revenue": 20000.00
        }
      ]
    },
    "by_user": {
      "total_users": 1500,
      "active_users_today": 200,
      "new_users": 15
    }
  }
}

---

🤖 供应商管理 API

基础路径: /api/providers

1. 获取模型供应商列表

端点: GET /api/providers/models

权限: ✅ 需要认证

查询参数: 无

响应 (200):

{
  "success": true,
  "data": {
    "providers": [
      {
        "id": "provider_uuid",
        "name": "OpenAI",
        "logo_url": "https://cdn.example.com/openai.png",
        "status": "active",
        "models": [
          {
            "id": "model_uuid",
            "name": "gpt-4",
            "display_name": "GPT-4",
            "max_tokens": 8192,
            "pricing": {
              "input_per_1k_tokens": 0.03,
              "output_per_1k_tokens": 0.06
            }
          }
        ]
      }
    ]
  }
}

---

2. 获取API供应商列表

端点: GET /api/providers/apis

权限: ✅ 需要认证

查询参数: 无

响应 (200):

{
  "success": true,
  "data": {
    "providers": [
      {
        "id": "provider_uuid",
        "name": "RapidAPI",
        "logo_url": "https://cdn.example.com/rapidapi.png",
        "status": "active",
        "api_count": 500,
        "categories": ["weather", "news", "sports"]
      }
    ]
  }
}

---

🛠️ 工具与集成 API

基础路径: /api/tools

1. 获取工具列表

端点: GET /api/tools?category={category}&status={status}

权限: ✅ 需要认证

查询参数:

参数	类型	必需	说明
category	string	❌	工具分类
status	enum	❌	active / inactive
page	int	❌	分页页码
limit	int	❌	每页条数

响应 (200):

{
  "success": true,
  "data": {
    "tools": [
      {
        "id": "tool_uuid",
        "name": "Weather API Tool",
        "description": "获取实时天气信息",
        "category": "weather",
        "status": "active",
        "endpoint": "https://api.taiji-ai.com/tools/weather",
        "method": "POST",
        "parameters": [
          {
            "name": "location",
            "type": "string",
            "description": "城市名称",
            "required": true
          }
        ],
        "rate_limit": 100,
        "cost_per_call": 0.05
      }
    ],
    "total": 120,
    "page": 1,
    "limit": 20
  }
}

---

2. 删除工具

端点: DELETE /api/tools/{toolId}

权限: ✅ 需要认证 (Tool Owner)

URL参数:

参数	说明
toolId	工具UUID

响应 (200):

{
  "success": true,
  "message": "工具已删除",
  "data": {
    "tool_id": "tool_uuid",
    "deleted_at": "2025-01-15T12:00:00Z"
  }
}

---

📊 统计与报告 API

基础路径: /api/stats

1. 获取平台统计数据

端点: GET /api/stats/overview?period={period}

权限: ✅ 需要认证

查询参数:

参数	类型	必需	说明
period	enum	❌	day / week / month / year

响应 (200):

{
  "success": true,
  "data": {
    "period": "month",
    "metrics": {
      "total_requests": 500000,
      "successful_requests": 495000,
      "failed_requests": 5000,
      "success_rate": 99.0,
      "average_latency_ms": 250,
      "p95_latency_ms": 800,
      "p99_latency_ms": 1500,
      "total_cost": 50000.00,
      "total_revenue": 75000.00
    }
  }
}

---

❌ 错误处理

错误响应格式

所有错误响应采用统一格式：

{
  "success": false,
  "data": null,
  "message": null,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": {}
  }
}

常见错误码

错误码	HTTP状态	说明
INVALID_REQUEST	400	请求参数错误
UNAUTHORIZED	401	未认证或Token过期
FORBIDDEN	403	无权访问
NOT_FOUND	404	资源不存在
CONFLICT	409	资源冲突（如重复创建）
INSUFFICIENT_BALANCE	402	余额不足
RATE_LIMIT_EXCEEDED	429	请求过于频繁
INTERNAL_ERROR	500	服务器内部错误

---

🔗 WebSocket API

实时通知连接

端点: WS /api/ws/notifications

认证: Query参数传递 ?token=<jwt_token>

事件类型:

{
  "type": "agent_status_change",
  "data": {
    "agent_id": "agent_uuid",
    "status": "running",
    "timestamp": "2025-01-15T12:00:00Z"
  }
}

---

📋 API使用示例

Python示例

import requests
import json

# 登录
response = requests.post(
    'http://localhost:8002/api/auth/login',
    json={
        'email': 'user@example.com',
        'password': 'password123',
        'role': 'user'
    }
)
token = response.json()['data']['token']

# 部署Agent
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json'
}

response = requests.post(
    'http://localhost:8002/api/user/agents/deploy',
    headers=headers,
    json={
        'agentId': 'agent_uuid',
        'instances': 2,
        'model': 'gpt-4o-mini',
        'gateway': 'MCP'
    }
)
print(json.dumps(response.json(), indent=2))

JavaScript/Node.js示例

const API_BASE_URL = 'http://localhost:8002';

// 登录
async function login(email, password) {
  const response = await fetch(`${API_BASE_URL}/api/auth/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password, role: 'user' })
  });
  const data = await response.json();
  return data.data.token;
}

// 部署Agent
async function deployAgent(token, agentId, instances) {
  const response = await fetch(`${API_BASE_URL}/api/user/agents/deploy`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      agentId,
      instances,
      model: 'gpt-4o-mini',
      gateway: 'MCP'
    })
  });
  return response.json();
}

// 使用
(async () => {
  const token = await login('user@example.com', 'password123');
  const result = await deployAgent(token, 'agent_uuid', 2);
  console.log(result);
})();

---

文档更新日期: 2025-01-15 版本: 2.0 维护者: Taiji AI Team