taijibaga/taiji-AI-PAD

Fork 0

forked from xiaohei/taiji-AI-PAD

Files

T

zhanggangyong 40447f86f6 更新开发者平台

2026-03-16 04:05:44 +00:00

12 KiB

Raw Permalink Blame History

开发者平台 API 使用指南

版本：v1.0
日期：2026-03-16
状态：已实现

概述

为已注册的租户用户提供 API Key 认证方式访问现有的 /api/user/* 接口，使开发者能够通过程序化方式（而非 Web UI）使用平台能力。

功能特性

✅ 双重认证支持

JWT Token 认证（Web UI 使用）
API Key 认证（程序调用使用）

✅ 灵活的认证方式

Authorization: Bearer <jwt_token> - JWT Token 认证
Authorization: Bearer sk-xxx - API Key 认证
X-API-Key: sk-xxx - API Key 认证

✅ 完整的 API Key 管理

创建带过期时间的 API Key
列出所有 API Keys
删除不需要的 API Key
查看使用统计

✅ 内置限流保护

每分钟 60 次请求
每日 10,000 次请求
自动返回限流响应头

快速开始

1. 创建 API Key

使用 JWT Token 登录后创建 API Key：

# 登录获取 JWT Token
curl -X POST "https://api.taiji-ai.com/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password",
    "role": "user"
  }'

# 响应示例
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    ...
  }
}

# 创建 API Key
curl -X POST "https://api.taiji-ai.com/api/auth/keys?name=MyAppKey&expires_in_days=30" \
  -H "Authorization: Bearer <jwt_token>"

# 响应示例
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "MyAppKey",
    "key": "sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "prefix": "sk-a1b2c...",
    "expiresAt": "2026-04-15T10:00:00Z",
    "createdAt": "2026-03-16T10:00:00Z"
  },
  "message": "API 密钥创建成功，请妥善保管，密钥只显示一次"
}

⚠️ 重要：API Key 只在创建时显示一次，请妥善保管！

2. 使用 API Key 调用接口

方式一：使用 Authorization Bearer

curl -X GET "https://api.taiji-ai.com/api/user/profile" \
  -H "Authorization: Bearer sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

方式二：使用 X-API-Key Header

curl -X GET "https://api.taiji-ai.com/api/user/profile" \
  -H "X-API-Key: sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

3. 查看限流信息

每次请求的响应头都会包含限流信息：

# 查看响应头
curl -i -X GET "https://api.taiji-ai.com/api/user/profile" \
  -H "Authorization: Bearer sk-xxx"

# 响应头示例
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
X-RateLimit-Limit-Daily: 10000
X-RateLimit-Remaining-Daily: 9999

API Key 管理接口

1. 创建新密钥

请求

POST /api/auth/keys?name={name}&expires_in_days={days}
Authorization: Bearer <jwt_token>

参数

name (可选): 密钥名称，默认 "API Key"
expires_in_days (可选): 过期天数，不填则永不过期

响应

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "MyAppKey",
    "key": "sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "prefix": "sk-a1b2c...",
    "expiresAt": "2026-04-15T10:00:00Z",
    "createdAt": "2026-03-16T10:00:00Z"
  },
  "message": "API 密钥创建成功，请妥善保管，密钥只显示一次"
}

2. 列出所有密钥

请求

GET /api/auth/keys
Authorization: Bearer <jwt_token or api_key>

响应

{
  "success": true,
  "data": {
    "keys": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "MyAppKey",
        "prefix": "sk-a1b2c...",
        "isActive": true,
        "createdAt": "2026-03-16T10:00:00Z",
        "lastUsed": "2026-03-16T11:30:00Z",
        "expiresAt": "2026-04-15T10:00:00Z",
        "totalRequests": 150
      }
    ],
    "total": 1
  },
  "message": "共 1 个 API 密钥"
}

3. 删除密钥

请求

DELETE /api/auth/keys/{key_id}
Authorization: Bearer <jwt_token>

响应

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "MyAppKey"
  },
  "message": "API 密钥 'MyAppKey' 已删除"
}

可用接口列表

所有 /api/user/* 接口都支持 API Key 认证，包括：

仪表盘与统计

GET /api/user/dashboard/stats - 获取仪表盘统计数据
GET /api/user/dashboard/billing-overview - 获取计费概览
GET /api/user/agents/activity - 获取 Agent 活动数据
GET /api/user/tools/stats - 获取工具统计数据

平台 Agent 管理

GET /api/user/platform-agents/available - 获取可用平台 Agent 模板
POST /api/user/platform-agents/deploy - 部署平台 Agent
POST /api/user/platform-agents/use - 使用/启动平台 Agent
GET /api/user/platform-agents/instances - 获取用户的 Agent 实例列表
GET /api/user/agents/platform - 获取平台 Agent 列表

自定义 Agent 管理

GET /api/user/custom-agents/templates - 获取自定义 Agent 模板
POST /api/user/custom-agents - 创建自定义 Agent
DELETE /api/user/custom-agents/{name} - 删除自定义 Agent
PUT /api/user/custom-agents/{name}/scale - 扩缩容自定义 Agent
GET /api/user/custom-agents - 获取自定义 Agent 列表
GET /api/user/custom-agents/{name}/logs - 获取 Agent 日志
POST /api/user/custom-agents/{name}/restart - 重启 Agent
POST /api/user/agents/deploy - 部署 Agent（通用）

工具管理

GET /api/user/tools - 获取用户工具列表
POST /api/user/tools/create - 创建工具
PUT /api/user/tools/{tool_id} - 更新工具

外部数据工具

POST /api/user/external-tools - 创建外部数据工具
POST /api/user/external-tools/upload - 上传 JSON 文件创建工具
GET /api/user/external-tools - 获取工具列表
GET /api/user/external-tools/{tool_id} - 获取工具详情
PUT /api/user/external-tools/{tool_id} - 更新工具配置
DELETE /api/user/external-tools/{tool_id} - 删除工具
POST /api/user/external-tools/{tool_id}/test - 测试工具连接

工具集

POST /api/user/toolkits - 创建工具集
GET /api/user/toolkits - 获取工具集列表
GET /api/user/toolkits/{toolkit_id} - 获取工具集详情
PUT /api/user/toolkits/{toolkit_id} - 更新工具集
DELETE /api/user/toolkits/{toolkit_id} - 删除工具集

工作流管理

POST /api/user/workflows/create - 创建工作流
GET /api/user/workflows - 获取工作流列表
POST /api/user/workflows/{workflow_id}/run - 运行工作流
DELETE /api/user/workflows/{workflow_id} - 删除工作流

模型管理

GET /api/user/models - 获取用户模型列表
GET /api/user/models/available - 获取可用模型列表
GET /api/user/models/usage/stats - 获取模型使用统计

计费管理

GET /api/user/billing/balance - 获取 EU 余额
GET /api/user/billing/history - 获取计费历史
GET /api/user/agent-billing/stats - 获取 Agent 计费统计
GET /api/user/agent-billing/history - 获取 Agent 计费历史

用户资料与资源

GET /api/user/profile - 获取用户资料
GET /api/user/resources/info - 获取用户资源信息
GET /api/user/resources/agents - 获取用户 Agent 资源

使用示例

Python 示例

import httpx

API_BASE = "https://api.taiji-ai.com"
API_KEY = "sk-your-api-key-here"

async def deploy_agent():
    async with httpx.AsyncClient() as client:
        # 部署平台 Agent
        response = await client.post(
            f"{API_BASE}/api/user/platform-agents/deploy",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json={
                "template": "code-reviewer",
                "name": "my-code-reviewer"
            }
        )
        
        if response.status_code == 200:
            data = response.json()
            print(f"Agent 部署成功: {data['data']['domainUrl']}")
        else:
            print(f"部署失败: {response.text}")

# 运行
import asyncio
asyncio.run(deploy_agent())

Node.js 示例

const axios = require('axios');

const API_BASE = 'https://api.taiji-ai.com';
const API_KEY = 'sk-your-api-key-here';

async function listAgents() {
  try {
    const response = await axios.get(
      `${API_BASE}/api/user/custom-agents`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    );
    
    console.log('Agents:', response.data.data);
    
    // 检查限流信息
    console.log('Rate Limit:');
    console.log('  Minute:', response.headers['x-ratelimit-remaining-minute']);
    console.log('  Daily:', response.headers['x-ratelimit-remaining-daily']);
  } catch (error) {
    if (error.response?.status === 429) {
      console.error('Rate limit exceeded');
      console.error('Retry after:', error.response.headers['retry-after'], 'seconds');
    } else {
      console.error('Error:', error.message);
    }
  }
}

listAgents();

限流说明

限流规则

限流类型	限制	重置周期
每分钟请求数 (RPM)	60 次	每分钟滚动
每日请求数 (Daily)	10,000 次	每日 UTC 0:00

限流响应

当超出限流时，API 会返回 429 Too Many Requests 状态码：

{
  "success": false,
  "error": "超出每分钟请求限制 (60)",
  "limit_type": "rpm",
  "limit": 60,
  "current": 61,
  "retry_after": 45
}

响应头：

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710586800
Retry-After: 45

最佳实践

监控限流响应头

remaining = response.headers.get('X-RateLimit-Remaining-Minute')
if int(remaining) < 10:
    print("警告：接近限流阈值")

实现退避重试

if response.status_code == 429:
    retry_after = int(response.headers.get('Retry-After', 60))
    await asyncio.sleep(retry_after)
    # 重试请求

批量操作
- 尽量使用批量接口
- 避免在循环中连续调用

安全最佳实践

1. 保护 API Key

❌ 不要这样做

# 硬编码在代码中
API_KEY = "sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

✅ 应该这样做

# 使用环境变量
import os
API_KEY = os.environ.get('TAIJI_API_KEY')

2. 使用 HTTPS

始终使用 HTTPS 连接，确保 API Key 在传输过程中加密。

3. 定期轮换密钥

为不同应用创建独立的 API Key
定期删除不使用的密钥
设置合理的过期时间

4. 限制权限范围

未来版本会支持 scope 权限控制，建议只授予必要的权限。

故障排查

问题 1: 401 Unauthorized

原因

API Key 无效或已过期
API Key 已被删除
认证头格式错误

解决方案

# 检查 API Key 是否有效
curl -X GET "https://api.taiji-ai.com/api/auth/keys" \
  -H "Authorization: Bearer <jwt_token>"

# 如果已失效，重新创建
curl -X POST "https://api.taiji-ai.com/api/auth/keys?name=NewKey" \
  -H "Authorization: Bearer <jwt_token>"

问题 2: 429 Too Many Requests

原因

超出每分钟或每日请求限制

解决方案

# 实现指数退避重试
import time

def call_api_with_retry(url, headers, max_retries=3):
    for i in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f"限流，等待 {retry_after} 秒...")
            time.sleep(retry_after)
            continue
        return response
    raise Exception("超过最大重试次数")

问题 3: 请求未被限流

原因

使用 JWT Token 认证（JWT 不受限流影响）
请求未通过认证

解决方案

确认使用 API Key 认证
检查 request.state.principal.type 是否为 "api_key"

更新日志

版本	日期	变更内容
v1.0	2026-03-16	初始实现，支持 API Key 认证和限流

技术支持

如有问题，请联系：

技术文档：https://docs.taiji-ai.com
技术支持：support@taiji-ai.com
GitHub Issues：https://github.com/taiji-ai/platform/issues

12 KiB Raw Permalink Blame History Unescape Escape

开发者平台 API 使用指南

概述

功能特性

快速开始

1. 创建 API Key

2. 使用 API Key 调用接口

方式一：使用 Authorization Bearer

方式二：使用 X-API-Key Header

3. 查看限流信息

API Key 管理接口

1. 创建新密钥

2. 列出所有密钥

3. 删除密钥

可用接口列表

仪表盘与统计

平台 Agent 管理

自定义 Agent 管理

工具管理

外部数据工具

工具集

工作流管理

模型管理

计费管理

用户资料与资源

使用示例

Python 示例

Node.js 示例

限流说明

限流规则

限流响应

最佳实践

安全最佳实践

1. 保护 API Key

2. 使用 HTTPS

3. 定期轮换密钥

4. 限制权限范围

故障排查

问题 1: 401 Unauthorized

问题 2: 429 Too Many Requests

问题 3: 请求未被限流

更新日志

技术支持

12 KiB

Raw Permalink Blame History