admin/aitsc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b728d729e6152ad96e805d99d1aa62a52fc33c69
aitsc/API_INTERFACE_DOCUMENTATION.md

14 KiB
Raw Blame History

提示词大师平台 API 接口文档

📋 文档概述

本文档提供了提示词大师平台的所有API接口，供第三方应用或新应用开发使用。

基础信息：

  • API版本： v1.0
  • 基础URL： http://localhost:5002/api
  • 数据格式： JSON
  • 认证方式： API Key / Session Token

🔐 认证接口

1. 获取API访问令牌

POST /api/auth/token
Content-Type: application/json

{
    "username": "your_username",
    "password": "your_password"
}

响应示例：

{
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600,
    "user_info": {
        "id": 1,
        "username": "your_username",
        "email": "user@example.com"
    }
}

2. 刷新访问令牌

POST /api/auth/refresh
Authorization: Bearer {token}

📝 模板管理接口

1. 获取模板列表

GET /api/templates?page=1&limit=20&category=all&search=关键词
Authorization: Bearer {token}

查询参数：

  • page: 页码（默认1）
  • limit: 每页数量（默认20，最大100）
  • category: 分类筛选
  • search: 搜索关键词
  • industry: 行业筛选
  • profession: 职业筛选
  • sub_category: 子分类筛选

响应示例：

{
    "success": true,
    "data": {
        "templates": [
            {
                "id": 1,
                "name": "通用优化",
                "description": "通用提示词优化",
                "category": "通用工具",
                "industry": "通用",
                "profession": "通用",
                "sub_category": "优化",
                "content": "你是一个专业的AI助手...",
                "usage_count": 1250,
                "rating": 4.8,
                "created_at": "2024-01-01T00:00:00Z",
                "updated_at": "2024-01-01T00:00:00Z"
            }
        ],
        "pagination": {
            "page": 1,
            "limit": 20,
            "total": 281,
            "pages": 15
        }
    }
}

2. 获取单个模板详情

GET /api/templates/{template_id}
Authorization: Bearer {token}

3. 创建新模板

POST /api/templates
Authorization: Bearer {token}
Content-Type: application/json

{
    "name": "新模板名称",
    "description": "模板描述",
    "category": "分类名称",
    "industry": "行业",
    "profession": "职业",
    "sub_category": "子分类",
    "content": "模板内容"
}

4. 更新模板

PUT /api/templates/{template_id}
Authorization: Bearer {token}
Content-Type: application/json

{
    "name": "更新后的名称",
    "description": "更新后的描述",
    "content": "更新后的内容"
}

5. 删除模板

DELETE /api/templates/{template_id}
Authorization: Bearer {token}

🎯 提示词生成接口

1. 生成提示词

POST /api/generate
Authorization: Bearer {token}
Content-Type: application/json

{
    "template_id": 1,
    "input_text": "用户输入的详细需求描述",
    "options": {
        "max_length": 1000,
        "style": "professional",
        "language": "zh-CN"
    }
}

响应示例：

{
    "success": true,
    "data": {
        "generated_text": "生成的提示词内容...",
        "template_used": {
            "id": 1,
            "name": "通用优化"
        },
        "generation_time": 1.2,
        "word_count": 150
    }
}

2. 批量生成提示词

POST /api/generate/batch
Authorization: Bearer {token}
Content-Type: application/json

{
    "requests": [
        {
            "template_id": 1,
            "input_text": "需求1"
        },
        {
            "template_id": 2,
            "input_text": "需求2"
        }
    ]
}

📊 分类管理接口

1. 获取所有分类

GET /api/categories
Authorization: Bearer {token}

响应示例：

{
    "success": true,
    "data": {
        "categories": [
            {
                "name": "通用工具",
                "description": "通用工具类模板",
                "icon": "fas fa-tools",
                "template_count": 45
            }
        ]
    }
}

2. 获取行业列表

GET /api/industries
Authorization: Bearer {token}

3. 获取职业列表

GET /api/professions
Authorization: Bearer {token}

4. 获取子分类列表

GET /api/sub-categories
Authorization: Bearer {token}

❤️ 收藏管理接口

1. 获取用户收藏列表

GET /api/favorites?page=1&limit=20
Authorization: Bearer {token}

2. 添加收藏

POST /api/favorites
Authorization: Bearer {token}
Content-Type: application/json

{
    "template_id": 1,
    "note": "个人备注"
}

3. 删除收藏

DELETE /api/favorites/{favorite_id}
Authorization: Bearer {token}

4. 快速添加收藏（包含生成内容）

POST /api/favorites/quick-add
Authorization: Bearer {token}
Content-Type: application/json

{
    "template_id": 1,
    "original_text": "用户原始输入",
    "generated_prompt": "生成的提示词",
    "category": "分类名称"
}

📈 统计接口

1. 获取平台统计信息

GET /api/stats/platform
Authorization: Bearer {token}

响应示例：

{
    "success": true,
    "data": {
        "total_templates": 281,
        "total_categories": 73,
        "total_generations": 15420,
        "total_users": 1250,
        "popular_templates": [
            {
                "id": 1,
                "name": "通用优化",
                "usage_count": 1250
            }
        ]
    }
}

2. 获取用户统计信息

GET /api/stats/user
Authorization: Bearer {token}

3. 获取模板使用统计

GET /api/stats/templates/{template_id}
Authorization: Bearer {token}

🔍 搜索接口

1. 智能搜索

GET /api/search?q=搜索关键词&type=template&limit=20
Authorization: Bearer {token}

查询参数：

  • q: 搜索关键词
  • type: 搜索类型（template, category, all）
  • limit: 结果数量限制

2. 获取热门搜索

GET /api/search/hot
Authorization: Bearer {token}

3. 获取搜索建议

GET /api/search/suggestions?q=关键词
Authorization: Bearer {token}

👤 用户管理接口

1. 获取用户信息

GET /api/user/profile
Authorization: Bearer {token}

2. 更新用户信息

PUT /api/user/profile
Authorization: Bearer {token}
Content-Type: application/json

{
    "username": "新用户名",
    "email": "newemail@example.com",
    "avatar": "头像URL"
}

3. 修改密码

PUT /api/user/password
Authorization: Bearer {token}
Content-Type: application/json

{
    "old_password": "旧密码",
    "new_password": "新密码"
}

📝 使用示例

Python 示例

import requests
import json

class PromptMasterAPI:
    def __init__(self, base_url="http://localhost:5002/api", token=None):
        self.base_url = base_url
        self.token = token
        self.headers = {
            "Content-Type": "application/json"
        }
        if token:
            self.headers["Authorization"] = f"Bearer {token}"
    
    def login(self, username, password):
        """用户登录获取token"""
        response = requests.post(
            f"{self.base_url}/auth/token",
            json={"username": username, "password": password}
        )
        data = response.json()
        if data["success"]:
            self.token = data["token"]
            self.headers["Authorization"] = f"Bearer {self.token}"
        return data
    
    def get_templates(self, page=1, limit=20, category="all", search=None):
        """获取模板列表"""
        params = {
            "page": page,
            "limit": limit,
            "category": category
        }
        if search:
            params["search"] = search
        
        response = requests.get(
            f"{self.base_url}/templates",
            headers=self.headers,
            params=params
        )
        return response.json()
    
    def generate_prompt(self, template_id, input_text, options=None):
        """生成提示词"""
        data = {
            "template_id": template_id,
            "input_text": input_text
        }
        if options:
            data["options"] = options
        
        response = requests.post(
            f"{self.base_url}/generate",
            headers=self.headers,
            json=data
        )
        return response.json()
    
    def add_favorite(self, template_id, note=None):
        """添加收藏"""
        data = {"template_id": template_id}
        if note:
            data["note"] = note
        
        response = requests.post(
            f"{self.base_url}/favorites",
            headers=self.headers,
            json=data
        )
        return response.json()

# 使用示例
api = PromptMasterAPI()

# 登录
result = api.login("your_username", "your_password")
if result["success"]:
    print("登录成功！")
    
    # 获取模板列表
    templates = api.get_templates(page=1, limit=10)
    print(f"找到 {templates['data']['pagination']['total']} 个模板")
    
    # 生成提示词
    if templates["data"]["templates"]:
        template_id = templates["data"]["templates"][0]["id"]
        result = api.generate_prompt(
            template_id=template_id,
            input_text="请帮我写一篇关于人工智能的文章"
        )
        if result["success"]:
            print("生成的提示词：", result["data"]["generated_text"])

JavaScript 示例

class PromptMasterAPI {
    constructor(baseUrl = 'http://localhost:5002/api', token = null) {
        this.baseUrl = baseUrl;
        this.token = token;
        this.headers = {
            'Content-Type': 'application/json'
        };
        if (token) {
            this.headers['Authorization'] = `Bearer ${token}`;
        }
    }
    
    async login(username, password) {
        const response = await fetch(`${this.baseUrl}/auth/token`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify({ username, password })
        });
        const data = await response.json();
        if (data.success) {
            this.token = data.token;
            this.headers['Authorization'] = `Bearer ${this.token}`;
        }
        return data;
    }
    
    async getTemplates(page = 1, limit = 20, category = 'all', search = null) {
        const params = new URLSearchParams({
            page: page.toString(),
            limit: limit.toString(),
            category: category
        });
        if (search) params.append('search', search);
        
        const response = await fetch(`${this.baseUrl}/templates?${params}`, {
            headers: this.headers
        });
        return await response.json();
    }
    
    async generatePrompt(templateId, inputText, options = null) {
        const data = {
            template_id: templateId,
            input_text: inputText
        };
        if (options) data.options = options;
        
        const response = await fetch(`${this.baseUrl}/generate`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify(data)
        });
        return await response.json();
    }
}

// 使用示例
const api = new PromptMasterAPI();

// 登录
api.login('your_username', 'your_password').then(result => {
    if (result.success) {
        console.log('登录成功！');
        
        // 获取模板列表
        return api.getTemplates(1, 10);
    }
}).then(templates => {
    if (templates && templates.success) {
        console.log(`找到 ${templates.data.pagination.total} 个模板`);
        
        // 生成提示词
        if (templates.data.templates.length > 0) {
            const templateId = templates.data.templates[0].id;
            return api.generatePrompt(templateId, '请帮我写一篇关于人工智能的文章');
        }
    }
}).then(result => {
    if (result && result.success) {
        console.log('生成的提示词：', result.data.generated_text);
    }
});

🚨 错误处理

错误响应格式

{
    "success": false,
    "error": {
        "code": "ERROR_CODE",
        "message": "错误描述信息",
        "details": "详细错误信息"
    }
}

常见错误码

  • AUTH_REQUIRED: 需要认证
  • INVALID_TOKEN: 无效的访问令牌
  • TOKEN_EXPIRED: 令牌已过期
  • PERMISSION_DENIED: 权限不足
  • RESOURCE_NOT_FOUND: 资源不存在
  • VALIDATION_ERROR: 参数验证失败
  • RATE_LIMIT_EXCEEDED: 请求频率超限
  • INTERNAL_ERROR: 服务器内部错误

📊 速率限制

  • 普通用户： 100次/小时
  • 高级用户： 1000次/小时
  • 企业用户： 10000次/小时

超过限制时返回 429 Too Many Requests 状态码。

🔧 开发建议

1. 环境准备

  • 确保现有服务正常运行在 http://localhost:5002
  • 准备测试账号和API访问权限
  • 安装必要的开发工具和SDK

2. 开发流程

  1. 接口测试： 使用Postman或curl测试所有接口
  2. SDK开发： 封装API调用为易用的SDK
  3. 错误处理： 实现完善的错误处理机制
  4. 缓存策略： 对模板列表等数据进行缓存
  5. 监控日志： 记录API调用日志和性能指标

3. 安全考虑

  • 使用HTTPS传输
  • 实现API Key轮换机制
  • 添加请求签名验证
  • 实现IP白名单限制

4. 性能优化

  • 实现请求缓存
  • 使用连接池
  • 添加重试机制
  • 实现异步处理

📞 技术支持

如有问题，请联系：

Reference in New Issue View Git Blame Copy Permalink