Maas-Model-platform/docs/inside/API/MD001_模型广场/MD001_模型广场后端API_V0.3.md

模型广场后端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

统一响应格式

{
  "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	视频生成

响应示例

{
  "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

响应示例

{
  "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"
  }
}

错误响应

{
  "code": 404,
  "message": "Model not found",
  "data": null
}

---

3. 获取关键字列表

GET /api/models/keywords/list

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "keywords": ["文本生成", "图像生成", "视频生成", "语音合成"]
  }
}

---

4. 获取精选模型列表

GET /api/models/featured/list

请求参数

参数	类型	必填	默认值	说明
limit	int	否	3	返回数量，范围1-10

响应示例

{
  "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	该阶梯输出单价

---

筛选示例

# 分类筛选
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