Files
Enterprise-Knowledge-Base/skills/openmaic-classroom/references/api-reference.md
T
bingxiang.cheng fff89d3abb feat(openmaic-classroom): 添加OpenMAIC互动课堂技能支持
- 新建openmaic-classroom技能文档,描述技能功能和使用流程
- 实现基于RAG检索结果和PDF生成互动课件的核心能力
- 支持托管模式和本地部署两种API调用方式
- 设计生成请求构建流程及任务状态轮询机制
- 实现多文档合成课程集的处理方案及错误处理说明
- 提供完整API接口参考,包括健康检查、生成任务、PDF解析等
- 添加需求构建指南,指导如何将检索结果转为课程需求
- 新增rag-to-requirement.py脚本,实现RAG结果向需求结构化转换
- 规范请求参数和返回格式,兼容多语言和教学深度设定
- 明确MCP调用工具的识别与降级策略,提升接口调用体验
2026-04-20 19:54:54 +08:00

298 lines
5.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# OpenMAIC API Reference
OpenMAIC 服务 API 接口规范。所有 API 基础路径为 `{base_url}/api`,默认 `http://localhost:3000/api`。
## 认证机制
- 如果 OpenMAIC 未设置 `ACCESS_CODE` 环境变量:所有接口开放
- 如果设置了 `ACCESS_CODE`:需先通过 `/api/access-code/verify` 获取 cookie
- `/api/health` 始终无需认证
### 获取认证 Cookie
```
POST {base_url}/api/access-code/verify
Content-Type: application/json
{ "code": "<ACCESS_CODE>" }
```
成功返回 `{ "success": true, "valid": true }` 并设置 `openmaic_access` cookie(7 天有效)。
## 标准响应格式
**成功**:
```json
{ "success": true, ...additionalFields }
```
**错误**:
```json
{ "success": false, "errorCode": "<Code>", "error": "<message>", "details?": "<detail>" }
```
---
## 核心端点
### 1. 健康检查
```
GET {base_url}/api/health
```
响应:
```json
{
"success": true,
"status": "ok",
"version": "0.1.0",
"capabilities": {
"webSearch": true,
"imageGeneration": false,
"videoGeneration": false,
"tts": true
}
}
```
> `capabilities` 用于功能检测,只在返回此字段时才启用对应的可选功能。
---
### 2. 生成课程(异步任务)
#### 2a. 创建生成任务
```
POST {base_url}/api/generate-classroom
Content-Type: application/json
```
请求体:
```json
{
"requirement": "教学主题描述",
"pdfContent": { "text": "PDF文本内容", "images": [] },
"enableWebSearch": false,
"enableImageGeneration": false,
"enableVideoGeneration": false,
"enableTTS": false,
"agentMode": "default"
}
```
成功响应 (202):
```json
{
"success": true,
"jobId": "abc123xyz",
"status": "queued",
"step": "queued",
"message": "Classroom generation job queued",
"pollUrl": "{base_url}/api/generate-classroom/abc123xyz",
"pollIntervalMs": 5000
}
```
错误:
- `400`: `requirement` 字段缺失
- `500`: 内部错误
#### 2b. 轮询任务状态
```
GET {pollUrl}
```
响应:
```json
{
"success": true,
"jobId": "abc123xyz",
"status": "running",
"step": "generating_outlines",
"progress": 35,
"message": "Generating scene outlines...",
"pollUrl": "...",
"pollIntervalMs": 5000,
"scenesGenerated": 2,
"totalScenes": 6,
"result": null,
"error": null,
"done": false
}
```
最终成功响应:
```json
{
"success": true,
"status": "succeeded",
"result": {
"classroomId": "Uyh82Y32ZK",
"url": "{base_url}/classroom/Uyh82Y32ZK",
"scenesCount": 6
},
"done": true
}
```
最终失败响应:
```json
{
"success": true,
"status": "failed",
"error": "具体错误信息",
"done": true
}
```
---
### 3. 解析 PDF
```
POST {base_url}/api/parse-pdf
Content-Type: multipart/form-data
```
表单字段:
- `pdf`(文件,必填): PDF 文件
- `providerId`(可选): PDF 提供商,默认 `"unpdf"`
- `apiKey`(可选): 提供商 API Key
- `baseUrl`(可选): 提供商基础 URL
响应:
```json
{
"success": true,
"data": {
"text": "提取的文本内容",
"images": [],
"metadata": {
"pageCount": 10,
"fileName": "document.pdf",
"fileSize": 1024000
}
}
}
```
---
### 4. 课程存储
#### 4a. 获取课程
```
GET {base_url}/api/classroom?id=<classroomId>
```
#### 4b. 持久化课程
```
POST {base_url}/api/classroom
Content-Type: application/json
{ "stage": {...}, "scenes": [...] }
```
---
### 5. Web 搜索
```
POST {base_url}/api/web-search
Content-Type: application/json
{ "query": "搜索关键词", "pdfText": "PDF上下文", "apiKey": "Tavily Key" }
```
---
### 6. 验证 LLM 连接
```
POST {base_url}/api/verify-model
Content-Type: application/json
{ "model": "openai:gpt-4o", "apiKey": "...", "baseUrl": "..." }
```
---
## 生成管线(逐步调用)
如果需要更细粒度的控制,可以使用以下逐步生成端点代替 `/api/generate-classroom`:
### A. 生成场景大纲(SSE 流)
```
POST {base_url}/api/generate/scene-outlines-stream
```
请求体:
```json
{
"requirements": { "requirement": "主题", "userNickname": "用户昵称" },
"pdfText": "PDF文本",
"pdfImages": [],
"researchContext": "网络搜索结果",
"agents": []
}
```
Headers:
- `x-image-generation-enabled`: `"true"` 或 `"false"`
- `x-video-generation-enabled`: `"true"` 或 `"false"`
SSE 事件类型:`languageDirective`、`outline`、`done`、`error`、`retry`
### B. 生成场景内容
```
POST {base_url}/api/generate/scene-content
Content-Type: application/json
{
"outline": {...},
"allOutlines": [...],
"stageId": "stage-1",
"pdfImages": [],
"agents": [],
"languageDirective": "使用简体中文"
}
```
### C. 生成场景动作
```
POST {base_url}/api/generate/scene-actions
Content-Type: application/json
{
"outline": {...},
"allOutlines": [...],
"content": {...},
"stageId": "stage-1",
"agents": [],
"languageDirective": "使用简体中文"
}
```
### D. 生成 Agent 画像
```
POST {base_url}/api/generate/agent-profiles
Content-Type: application/json
{
"stageInfo": { "name": "入门阶段", "description": "..." },
"sceneOutlines": [{ "title": "...", "description": "..." }],
"languageDirective": "使用简体中文",
"availableAvatars": [],
"avatarDescriptions": []
}
```