1818web-hoduan/AI_MODEL_API_GUIDE.md

AI模型查询接口使用指南

概述

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

接口列表

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

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

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

请求参数:

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

响应示例:

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

使用示例:

// 获取所有已启用的模型
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

响应示例:

{
  "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
        }
        // ... 更多视频模型
      ]
    }
  ]
}

使用示例:

// 获取所有按类型分组的模型
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

响应示例:

{
  "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模型
      ]
    }
  ]
}

使用示例:

// 获取所有按厂商分组的模型
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模型的统计信息

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "totalModels": 10,
    "enabledModels": 8,
    "countByType": {
      "image": 2,
      "video": 5,
      "audio": 1
    },
    "countByProvider": {
      "openai": 3,
      "runninghub": 5
    }
  }
}

---

前端集成示例

Vue 3 + 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组件）

<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模式）

展示所有可用模型供用户选择：

GET /user/ai/models?enabledOnly=true

场景2: 按类型筛选（文生图）

用户想要生成图片，只显示图片生成模型：

GET /user/ai/models?taskType=image

场景3: 按厂商分类展示

展示不同AI服务商的模型，方便用户对比：

GET /user/ai/models/group-by-provider

场景4: 特定厂商的特定类型

显示RunningHub的视频生成模型：

GET /user/ai/models?taskType=video&provider=runninghub

场景5: 模型统计Dashboard

显示系统模型概览：

GET /user/ai/models/stats

---

数据模型说明

任务类型 (taskType)

• image - 图片生成（文生图、图生图等）
• video - 视频生成（文生视频、图生视频等）
• audio - 音频生成
• text - 文本生成
• other - 其他类型

服务提供商 (providerType)

• openai - OpenAI
• runninghub - RunningHub
• anthropic - Anthropic
• google - Google
• 其他自定义提供商

扩展配置 (extendedConfig)

JSON格式的模型特定配置，例如：

{
  "webappId": "1973555977595301890",
  "defaultDuration": 10,
  "supportedSizes": ["portrait", "landscape"],
  "maxDuration": 15
}

---

注意事项

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