Files
Enterprise-Knowledge-Base/skills/preloaded/openmaic-classroom/references/api-reference.md
T
bingxiang.cheng 8f671817a3 refactor(openmaic-classroom): 规范文档并强化mcp-api-requester调用要求
- 重新排版和规范技能说明文档,提升可读性
- 明确强调必须使用WeKnora的mcp-api-requester MCP工具调用OpenMAIC API
- 取消curl命令降级方案,改为引导用户部署mcp-api-requester服务
- 增强本地模式Base URL处理,替换localhost和127.0.0.1为host.docker.internal
- 完善错误处理和任务状态查询流程说明
- 更新API参考文档,统一接口描述和响应格式
- 细化多文档生成课程集的调用和错误引导逻辑
- 提示单次生成任务时间及托管模式配额限制
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": []
}
```