# 模型广场后端API文档 V0.2

## 基础信息

- **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 | TTS语音合成模型 |
| 语音 | 3 | 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,
        "input_price": "0.0001",
        "output_price": "0.0002",
        "price_unit": "tokens",
        "price_currency": "CNY",
        "created_at": "2025-01-01T00:00:00",
        "updated_at": "2025-01-01T00:00:00"
      }
    ]
  }
}
```

---

### 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"
  }
}
```

#### 错误响应

模型不存在时返回404：

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

---

### 3. 获取所有关键字列表

**GET** `/api/models/keywords/list`

#### 请求参数

无

#### 响应示例

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

---

## 数据字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| id | int | 模型ID |
| title | string | 模型标识（唯一） |
| img | string | 图标URL |
| name | string | 显示名称 |
| tag1 | string | 主标签 |
| description | string | 模型描述 |
| keyword | string | 关键词 |
| time | string | 发布时间 |
| tag2 | string | 次要标签 |
| category | int | 模型分类：0=文本，1=多模态，2=TTS，3=STT，4=生图，5=生视频 |
| supplier | string | 供应商名称，默认Qwen |
| price_id | int | 价格ID（外键关联model_price表），可为null |
| is_featured | boolean | 是否为精选模型 |
| input_price | decimal | 输入单价（仅列表接口返回），可为null |
| output_price | decimal | 输出单价（仅列表接口返回），可为null |
| price_unit | string | 计价单位（仅列表接口返回），可为null |
| price_currency | string | 货币单位（仅列表接口返回），可为null |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

---

## 筛选功能说明

### 分类筛选

使用 `category` 参数按模型分类筛选：

```
GET /api/models?category=文本
```

可选括值：`文本`、`图像`、`视频`、`语音`

### 供应商筛选

使用 `supplier` 参数精确匹配供应商：

```
GET /api/models?supplier=Qwen
```

### 关键字筛选

使用 `filter_keyword` 参数精确匹配关键字字段：

```
GET /api/models?filter_keyword=文本生成
```

### 标签筛选

使用 `filter_tag` 参数在tag1或tag2中精确匹配：

```
GET /api/models?filter_tag=高速
```

### 组合筛选

多个筛选条件可以组合使用：

```
GET /api/models?category=文本&supplier=Qwen&filter_tag=高速
```

---

## 在线文档

启动服务后访问：
- Swagger UI: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`