# 模型广场后端API文档 V0.4 ## 更新日志 | 版本 | 日期 | 更新内容 | |------|------|----------| | V0.4 | 2024-12-29 | 新增获取精选模型接口 | | V0.3 | 2024-12-29 | 新增阶梯价格支持，完善价格字段说明 | | V0.2 | 2024-12-28 | 新增筛选功能 | | V0.1 | 2024-12-27 | 初始版本 | ## 基础信息 - **Base URL**: `http://localhost:8000` - **API前缀**: `/api/models` ## 统一响应格式 ```json { "code": 200, "message": "success", "data": {} } ``` | 字段 | 类型 | 说明 | |------|------|------| | code | int | 状态码：200成功，400参数错误，404资源不存在，500服务器错误 | | message | string | 响应消息 | | data | object | 响应数据 | --- ## 接口列表 ### 1. 获取模型列表 **GET** `/api/models` #### 请求参数 | 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | page | int | 否 | 1 | 页码，最小值1 | | page_size | int | 否 | 20 | 每页数量，范围1-100 | | keyword | string | 否 | - | 搜索关键词，在name、description、keyword字段中模糊匹配 | | category | string | 否 | - | 模型分类筛选，可选值：文本、图像、视频、语音 | | supplier | string | 否 | - | 供应商筛选，精确匹配供应商名称 | | filter_keyword | string | 否 | - | 关键字筛选，精确匹配keyword字段 | | filter_tag | string | 否 | - | 标签筛选，在tag1或tag2字段中精确匹配 | #### 分类映射关系 | 前端分类 | 数据库category值 | 说明 | |----------|-----------------|------| | 文本 | 0 | 语言模型(LLM) | | 图像 | 1, 4 | 多模态/图像生成 | | 语音 | 2, 3 | TTS/STT | | 视频 | 5 | 视频生成 | #### 响应示例 ```json { "code": 200, "message": "success", "data": { "total": 100, "page": 1, "page_size": 20, "items": [ { "id": 1, "title": "qwen-turbo", "img": "https://example.com/icon.svg", "name": "通义千问-Turbo", "tag1": "高速", "description": "通义千问超大规模语言模型", "keyword": "文本生成", "time": "2025-01-01", "tag2": "Qwen", "category": 0, "supplier": "Qwen", "price_id": 1, "is_featured": true, "created_at": "2025-01-01T00:00:00", "updated_at": "2025-01-01T00:00:00", "pricing_mode": "simple", "input_price": "0.0001", "output_price": "0.0002", "price_unit": "tokens", "price_currency": "CNY", "price_tiers": [] }, { "id": 2, "title": "qwen-max", "img": "https://example.com/icon.svg", "name": "通义千问-Max", "tag1": "旗舰", "description": "通义千问旗舰模型", "keyword": "文本生成", "time": "2025-01-01", "tag2": "Qwen", "category": 0, "supplier": "Qwen", "price_id": 2, "is_featured": true, "created_at": "2025-01-01T00:00:00", "updated_at": "2025-01-01T00:00:00", "pricing_mode": "tier", "input_price": "0.0001", "output_price": "0.0002", "price_unit": "tokens", "price_currency": "CNY", "price_tiers": [ { "tier_min": 0, "tier_max": 100000, "input_price": "0.0001", "output_price": "0.0002" }, { "tier_min": 100000, "tier_max": null, "input_price": "0.00008", "output_price": "0.00016" } ] } ] } } ``` --- ### 2. 获取单个模型详情 **GET** `/api/models/{model_id}` #### 路径参数 | 参数 | 类型 | 说明 | |------|------|------| | model_id | int | 模型ID | #### 响应示例 ```json { "code": 200, "message": "success", "data": { "id": 1, "title": "qwen-turbo", "img": "https://example.com/icon.svg", "name": "通义千问-Turbo", "tag1": "高速", "description": "通义千问超大规模语言模型", "keyword": "文本生成", "time": "2025-01-01", "tag2": "Qwen", "category": 0, "supplier": "Qwen", "price_id": 1, "is_featured": true, "created_at": "2025-01-01T00:00:00", "updated_at": "2025-01-01T00:00:00" } } ``` #### 错误响应 ```json { "code": 404, "message": "Model not found", "data": null } ``` --- ### 3. 获取关键字列表 **GET** `/api/models/keywords/list` #### 响应示例 ```json { "code": 200, "message": "success", "data": { "keywords": ["文本生成", "图像生成", "视频生成", "语音合成"] } } ``` --- ### 4. 获取精选模型列表 **GET** `/api/models/featured/list` #### 请求参数 | 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | limit | int | 否 | 3 | 返回数量，范围1-10 | #### 响应示例 ```json { "code": 200, "message": "success", "data": { "items": [ { "id": 1, "title": "qwen-turbo", "img": "https://example.com/icon.svg", "name": "通义千问-Turbo", "tag1": "高速", "description": "通义千问超大规模语言模型", "keyword": "文本生成", "time": "2025-01-01", "tag2": "Qwen", "category": 0, "supplier": "Qwen", "price_id": 1, "is_featured": true, "created_at": "2025-01-01T00:00:00", "updated_at": "2025-01-01T00:00:00", "pricing_mode": "simple", "input_price": "0.0001", "output_price": "0.0002", "price_unit": "tokens", "price_currency": "CNY", "price_tiers": [] } ] } } ``` --- ## 数据字段说明 ### 模型基础字段 | 字段 | 类型 | 说明 | |------|------|------| | id | int | 模型ID | | title | string | 模型标识（唯一） | | img | string | 图标URL | | name | string | 显示名称 | | tag1 | string | 主标签 | | description | string | 模型描述 | | keyword | string | 关键词 | | time | string | 发布时间 | | tag2 | string | 次要标签 | | category | int | 模型分类 | | supplier | string | 供应商名称 | | price_id | int | 价格ID | | is_featured | boolean | 是否精选 | | created_at | datetime | 创建时间 | | updated_at | datetime | 更新时间 | ### 价格相关字段（仅列表接口） | 字段 | 类型 | 说明 | |------|------|------| | pricing_mode | string | 计价模式：simple=简单计费，tier=阶梯计费 | | input_price | decimal | 输入单价 | | output_price | decimal | 输出单价 | | price_unit | string | 计价单位，默认tokens | | price_currency | string | 货币单位，默认CNY | | price_tiers | array | 阶梯价格列表 | ### 阶梯价格字段 | 字段 | 类型 | 说明 | |------|------|------| | tier_min | int | 阶梯起始token数 | | tier_max | int | 阶梯结束token数，null表示无上限 | | input_price | decimal | 该阶梯输入单价 | | output_price | decimal | 该阶梯输出单价 | --- ## 筛选示例 ```bash # 分类筛选 GET /api/models?category=文本 # 供应商筛选 GET /api/models?supplier=Qwen # 关键字筛选 GET /api/models?filter_keyword=文本生成 # 标签筛选 GET /api/models?filter_tag=高速 # 组合筛选 GET /api/models?category=文本&supplier=Qwen&page=1&page_size=10 # 获取精选模型（默认3个） GET /api/models/featured/list # 获取指定数量的精选模型 GET /api/models/featured/list?limit=5 ``` --- ## 在线文档 - Swagger UI: `http://localhost:8000/docs` - ReDoc: `http://localhost:8000/redoc`