API 接口指南

API 接口指南

后端 API 遵循 统一入口 + 内部分发 的插件式架构，共 4 个生成类核心接口 + 3 个只读状态接口。

接口一览

路径用途分发方式
/api/chatAI 对话（流式/非流式）model.provider（POST）
/api/image图片生成model.provider（POST）
/api/audio语音合成（TTS）model.provider（POST）
/api/video视频生成model.provider（POST）
/api/github/commit查询 GitHub 提交日期固定（POST）
/api/github/overview分支动态、提交时间线与差异固定（GET）
/api/status服务端配置状态固定（GET）

生成类接口统一接收 POST 请求，Content-Type: application/json；只读状态接口使用 GET，不接收外部入参。

目录结构

server/api/
├── chat/                  ← AI 对话
│   ├── index.ts           ← 路由分发
│   └── providers/
│       └── aisdk.ts       ← AI SDK 对话（流式 + 非流式）
├── image/                 ← 图片生成
│   ├── index.ts
│   └── providers/
│       ├── bigmodel.ts    ← BigModel 平台
│       └── agnes.ts       ← Agnes 平台
├── audio/                 ← 语音合成
│   ├── index.ts
│   └── providers/
│       ├── xiaomi.ts      ← 小米 TTS（同步）
│       └── gitee.ts       ← Gitee Audio（异步任务）
├── video/                 ← 视频生成
│   ├── index.ts
│   └── providers/
│       └── agnes.ts       ← Agnes（异步任务）
├── github/
│   ├── commit.js          ← 轻量部署日期接口（保持旧契约）
│   └── overview.get.ts    ← 双分支动态聚合接口
└── status.get.ts          ← 服务端配置状态（不外联第三方）

路由分发机制

每个 index.ts 从请求体中读取 model.provider，查表分发到对应的 provider：

import { handle as aisdk } from './providers/aisdk'

const handlers: Record<string, (body: any) => any> = {
  aisdk,
}

export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  const provider = body?.model?.provider
  if (!provider) {
    throw createError({
      statusCode: 400,
      statusMessage: `不支持的 provider: ${provider}`,
    })
  }
  // 未注册的 provider 回退到通用 aisdk handler
  const handler = handlers[provider] || handlers.aisdk
  return handler(body)
})

添加厂家 = 在 providers/ 下新建文件 + 在 handlers 中注册一行（可选）。 若未注册，自动回退到通用 aisdk handler（仅适用于 OpenAI 兼容接口）。 删除厂家 = 删除 provider 文件 + 从 handlers 中去掉对应行。互不影响。

接口详情

/api/chat — AI 对话

POST /api/chat
Body: { messages, model, system?, providerOptions?, stream? }
  • stream: true（默认）→ 返回 SSE 流（ai SDK 的 toUIMessageStreamResponse）
  • stream: false → 返回 { result: string }

当前 provider：

provider说明
aisdk（通用回退）通用 OpenAI 兼容接口，未注册的 provider（如 InternAi、BigModel、OpenRouter、Agnes）自动回退至此

/api/image — 图片生成

POST /api/image
Body: { prompt, model, n?, size?, quality?, seed?, tags?, image? }

当前 provider：

provider说明特有字段
bigmodelBigModel 平台size, quality
agnesAgnes 平台size, seed, tags, image

返回格式：{ images: [{ base64, mediaType }], originalUrls: string[] }

/api/audio — 语音合成

POST /api/audio
Body: { model, text, style?, voice?, format?, task?, input?, taskId? }

当前 provider：

provider说明请求字段返回
xiaomi小米 TTS（同步）model, text, style?, voice?, format?{ base64, mediaType }
giteeGitee（异步任务）task: 'create', model, input{ taskId }
查询任务task: 'query', taskId, model{ status, file_url }
  • 同步 provider 直接返回音频 base64 数据
  • 异步 provider 需客户端先 create 获取 taskId，再轮询 query 直到 status === 'success'

/api/video — 视频生成

POST /api/video
Body: { task, model, prompt?, taskId?, image?, num_frames?, ... }

当前 provider：

provider说明
agnesAgnes 视频生成（异步任务）
  • task: 'create' → { taskId, status, progress }
  • task: 'query' → { status, progress, video_url }

客户端创建任务后轮询 query 直到 status === 'completed'。

/api/github/commit — 部署状态

POST /api/github/commit
Body: { branch }
返回: "2026-06-15"

branch 仅允许 main 与 develop（白名单校验），返回 YYYY-MM-DD 字符串，契约保持不变。

/api/github/overview — 分支更新动态

GET /api/github/overview
GET /api/github/overview?refresh=1   // 手动刷新，绕过常规缓存
返回: GithubOverview（契约见 app/types/github.ts）

服务端并行请求 GitHub REST（两个 commits/{branch} 详情、两个 commits?sha=... 列表、compare/main...develop），任意一路失败只把对应区块写入 warnings，其余数据照常返回。响应包含：

  • branches：main / develop 最新提交时间、标题、作者、短 SHA、变更统计与站点地址
  • compare：aheadBy（develop 领先）/ behindBy（develop 落后）
  • timeline：两分支合并去重后按时间倒序的最近 4 条提交
  • contributors / warnings / fetchedAt

使用 defineCachedEventHandler 缓存 90 秒并开启 stale-while-revalidate；githubApiToken 仅在服务端使用，未配置时按公开仓库匿名读取。

/api/status — 服务端配置状态

GET /api/status
返回: { configured: { agnesApiKey: true, ... }, checkedAt: "..." }

仅读取 useRuntimeConfig() 判断各项密钥是否已配置，不返回密钥内容、不探测第三方服务，用于概览页展示当前模型的配置就绪提示。

Provider 开发规范

每个 provider 文件导出一个 handle 函数：

export async function handle(body: YourType) {
  // 1. 校验必要字段
  // 2. 通过 useRuntimeConfig() 获取 API Key
  // 3. 调用第三方 API
  // 4. 返回统一格式的响应
}
  • 不调用 readBody(event)——body 已由 index.ts 解析传入
  • 不处理路由逻辑——只负责具体厂商的 API 调用
  • 错误统一使用 createError 抛出