ContextQMD
Back to Weknora

OpenMAIC API Reference

skills/preloaded/openmaic-classroom/references/api-reference.md

0.5.15.2 KB
Original Source

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