[Claude Workbench] Initial commit - preserving existing code
This commit is contained in:
Claude Workbench
437
AI_MODEL_API_GUIDE.md
Normal file
437
AI_MODEL_API_GUIDE.md
Normal file
@@ -0,0 +1,437 @@
|
||||
# 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. **分组查询**: 提供按类型和按厂商两种分组方式，方便前端展示
|
||||
|
||||
Reference in New Issue
Block a user