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

5.2 KiB
Raw Blame History

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 始终无需认证
POST {base_url}/api/access-code/verify
Content-Type: application/json

{ "code": "<ACCESS_CODE>" }

成功返回 { "success": true, "valid": true } 并设置 openmaic_access cookie(7 天有效)。

标准响应格式

成功:

{ "success": true, ...additionalFields }

错误:

{ "success": false, "errorCode": "<Code>", "error": "<message>", "details?": "<detail>" }

核心端点

1. 健康检查

GET {base_url}/api/health

响应:

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

请求体:

{
  "requirement": "教学主题描述",
  "pdfContent": { "text": "PDF文本内容", "images": [] },
  "enableWebSearch": false,
  "enableImageGeneration": false,
  "enableVideoGeneration": false,
  "enableTTS": false,
  "agentMode": "default"
}

成功响应 (202):

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

响应:

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

最终成功响应:

{
  "success": true,
  "status": "succeeded",
  "result": {
    "classroomId": "Uyh82Y32ZK",
    "url": "{base_url}/classroom/Uyh82Y32ZK",
    "scenesCount": 6
  },
  "done": true
}

最终失败响应:

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

响应:

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

请求体:

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