# AI模型查询接口使用指南

## 概述

系统提供了完整的用户端AI模型查询接口，支持多种查询和分组方式。所有接口均为公开访问，无需认证。

## 接口列表

### 1. 获取模型列表（支持筛选）

**接口地址**: `GET /user/ai/models`

**描述**: 获取所有可用的AI模型列表，支持按任务类型和厂商筛选

**请求参数**:
- `taskType` (可选): 任务类型
  - `image` - 图片生成
  - `video` - 视频生成
  - `audio` - 音频生成
  - `text` - 文本生成
- `provider` (可选): 服务提供商
  - `openai` - OpenAI
  - `runninghub` - RunningHub
- `enabledOnly` (可选): 是否只返回已启用的模型，默认 `true`

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "modelName": "sora_image",
      "displayName": "Sora高质量图片生成",
      "description": "Sora高质量图片生成",
      "pointsCost": 11,
      "providerType": "openai",
      "taskType": "image",
      "isEnabled": true,
      "extendedConfig": {}
    },
    {
      "id": 2,
      "modelName": "sora_video2",
      "displayName": "Sora视频生成 (竖屏10秒)",
      "description": "Sora视频生成 (竖屏10秒)",
      "pointsCost": 160,
      "providerType": "runninghub",
      "taskType": "video",
      "isEnabled": true,
      "extendedConfig": {
        "webappId": "1973555977595301890",
        "defaultDuration": 10
      }
    }
  ]
}
```

**使用示例**:
```javascript
// 获取所有已启用的模型
GET /user/ai/models

// 获取所有图片生成模型
GET /user/ai/models?taskType=image

// 获取OpenAI的所有模型
GET /user/ai/models?provider=openai

// 获取RunningHub的视频生成模型
GET /user/ai/models?taskType=video&provider=runninghub

// 获取所有模型（包括未启用的）
GET /user/ai/models?enabledOnly=false
```

---

### 2. 按类型分组获取模型

**接口地址**: `GET /user/ai/models/group-by-type`

**描述**: 获取按任务类型分组的AI模型列表

**请求参数**:
- `provider` (可选): 服务提供商筛选
- `enabledOnly` (可选): 是否只返回已启用的模型，默认 `true`

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "taskType": "image",
      "taskTypeName": "图片生成",
      "count": 2,
      "models": [
        {
          "id": 1,
          "modelName": "sora_image",
          "displayName": "Sora高质量图片生成",
          "pointsCost": 11,
          "providerType": "openai",
          "taskType": "image",
          "isEnabled": true
        },
        {
          "id": 2,
          "modelName": "gpt-4o-image",
          "displayName": "GPT-4o图片生成",
          "pointsCost": 11,
          "providerType": "openai",
          "taskType": "image",
          "isEnabled": true
        }
      ]
    },
    {
      "taskType": "video",
      "taskTypeName": "视频生成",
      "count": 4,
      "models": [
        {
          "id": 3,
          "modelName": "sora_video2",
          "displayName": "Sora视频生成 (竖屏10秒)",
          "pointsCost": 160,
          "providerType": "runninghub",
          "taskType": "video",
          "isEnabled": true
        }
        // ... 更多视频模型
      ]
    }
  ]
}
```

**使用示例**:
```javascript
// 获取所有按类型分组的模型
GET /user/ai/models/group-by-type

// 获取OpenAI的按类型分组的模型
GET /user/ai/models/group-by-type?provider=openai

// 获取所有模型按类型分组（包括未启用的）
GET /user/ai/models/group-by-type?enabledOnly=false
```

---

### 3. 按厂商分组获取模型

**接口地址**: `GET /user/ai/models/group-by-provider`

**描述**: 获取按服务提供商分组的AI模型列表

**请求参数**:
- `taskType` (可选): 任务类型筛选
- `enabledOnly` (可选): 是否只返回已启用的模型，默认 `true`

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "providerType": "openai",
      "providerName": "OpenAI",
      "count": 2,
      "models": [
        {
          "id": 1,
          "modelName": "sora_image",
          "displayName": "Sora高质量图片生成",
          "pointsCost": 11,
          "providerType": "openai",
          "taskType": "image",
          "isEnabled": true
        },
        {
          "id": 2,
          "modelName": "gpt-4o-image",
          "displayName": "GPT-4o图片生成",
          "pointsCost": 11,
          "providerType": "openai",
          "taskType": "image",
          "isEnabled": true
        }
      ]
    },
    {
      "providerType": "runninghub",
      "providerName": "RunningHub",
      "count": 5,
      "models": [
        {
          "id": 3,
          "modelName": "sora_video2",
          "displayName": "Sora视频生成 (竖屏10秒)",
          "pointsCost": 160,
          "providerType": "runninghub",
          "taskType": "video",
          "isEnabled": true
        }
        // ... 更多RunningHub模型
      ]
    }
  ]
}
```

**使用示例**:
```javascript
// 获取所有按厂商分组的模型
GET /user/ai/models/group-by-provider

// 获取视频生成的按厂商分组
GET /user/ai/models/group-by-provider?taskType=video

// 获取图片生成的按厂商分组
GET /user/ai/models/group-by-provider?taskType=image
```

---

### 4. 获取模型统计信息

**接口地址**: `GET /user/ai/models/stats`

**描述**: 获取系统中AI模型的统计信息

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "totalModels": 10,
    "enabledModels": 8,
    "countByType": {
      "image": 2,
      "video": 5,
      "audio": 1
    },
    "countByProvider": {
      "openai": 3,
      "runninghub": 5
    }
  }
}
```

---

## 前端集成示例

### Vue 3 + TypeScript 示例

```typescript
// api/aiModel.ts
import axios from 'axios';

interface ModelInfo {
  id: number;
  modelName: string;
  displayName: string;
  description: string;
  pointsCost: number;
  providerType: string;
  taskType: string;
  isEnabled: boolean;
  extendedConfig?: Record<string, any>;
}

interface ModelsByType {
  taskType: string;
  taskTypeName: string;
  count: number;
  models: ModelInfo[];
}

export const aiModelApi = {
  // 获取所有模型
  getAllModels(params?: {
    taskType?: string;
    provider?: string;
    enabledOnly?: boolean;
  }) {
    return axios.get<{ data: ModelInfo[] }>('/user/ai/models', { params });
  },

  // 按类型分组获取
  getModelsByType(params?: {
    provider?: string;
    enabledOnly?: boolean;
  }) {
    return axios.get<{ data: ModelsByType[] }>('/user/ai/models/group-by-type', { params });
  },

  // 按厂商分组获取
  getModelsByProvider(params?: {
    taskType?: string;
    enabledOnly?: boolean;
  }) {
    return axios.get<{ data: any[] }>('/user/ai/models/group-by-provider', { params });
  },

  // 获取统计信息
  getModelStats() {
    return axios.get('/user/ai/models/stats');
  }
};
```

### 使用示例（Vue组件）

```vue
<template>
  <div class="model-selector">
    <!-- 按类型分组显示 -->
    <div v-for="typeGroup in modelsByType" :key="typeGroup.taskType">
      <h3>{{ typeGroup.taskTypeName }} ({{ typeGroup.count }})</h3>
      <div class="model-list">
        <div 
          v-for="model in typeGroup.models" 
          :key="model.id"
          class="model-card"
          @click="selectModel(model)"
        >
          <h4>{{ model.displayName }}</h4>
          <p>{{ model.description }}</p>
          <span class="cost">{{ model.pointsCost }} 积分</span>
          <span class="provider">{{ model.providerType }}</span>
        </div>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { aiModelApi } from '@/api/aiModel';

const modelsByType = ref<ModelsByType[]>([]);

onMounted(async () => {
  const { data } = await aiModelApi.getModelsByType();
  modelsByType.value = data.data;
});

function selectModel(model: ModelInfo) {
  console.log('Selected model:', model);
  // 处理模型选择逻辑
}
</script>
```

---

## 常见使用场景

### 场景1: 模型选择器（ALL模式）
展示所有可用模型供用户选择：
```javascript
GET /user/ai/models?enabledOnly=true
```

### 场景2: 按类型筛选（文生图）
用户想要生成图片，只显示图片生成模型：
```javascript
GET /user/ai/models?taskType=image
```

### 场景3: 按厂商分类展示
展示不同AI服务商的模型，方便用户对比：
```javascript
GET /user/ai/models/group-by-provider
```

### 场景4: 特定厂商的特定类型
显示RunningHub的视频生成模型：
```javascript
GET /user/ai/models?taskType=video&provider=runninghub
```

### 场景5: 模型统计Dashboard
显示系统模型概览：
```javascript
GET /user/ai/models/stats
```

---

## 数据模型说明

### 任务类型 (taskType)
- `image` - 图片生成（文生图、图生图等）
- `video` - 视频生成（文生视频、图生视频等）
- `audio` - 音频生成
- `text` - 文本生成
- `other` - 其他类型

### 服务提供商 (providerType)
- `openai` - OpenAI
- `runninghub` - RunningHub
- `anthropic` - Anthropic
- `google` - Google
- 其他自定义提供商

### 扩展配置 (extendedConfig)
JSON格式的模型特定配置，例如：
```json
{
  "webappId": "1973555977595301890",
  "defaultDuration": 10,
  "supportedSizes": ["portrait", "landscape"],
  "maxDuration": 15
}
```

---

## 注意事项

1. **公开访问**: 所有模型查询接口均为公开访问，无需登录
2. **默认过滤**: 默认只返回已启用的模型（`enabledOnly=true`）
3. **智能推断**: 系统会根据模型名称自动推断任务类型
4. **灵活组合**: 可以组合多个参数进行精确筛选
5. **分组查询**: 提供按类型和按厂商两种分组方式，方便前端展示