跳转至

教材接口

教材接口提供基于 AI 的动态教材生成能力，支持多种内容类型（文本、图片、视频、交互组件），采用异步生成架构，支持实时进度轮询。

测试阶段（Beta）

该功能目前处于 测试阶段，尚未正式上线，仅在测试环境中可用。

  • 测试环境基础 URL：https://test.api.upath.cn
  • 请使用测试环境对应的 API Key 进行调用（与生产环境的 API Key 不通用）
  • 测试阶段接口行为和参数可能会发生变更，请关注文档更新

认证方式

所有教材接口需要使用 API Key 认证，请在请求头中添加 X-API-Key。

接口列表

接口 方法 说明
/api/curriculum/ POST 创建教材（异步生成）
/api/curriculum/ GET 获取教材列表
/api/curriculum/{id}/ GET 获取教材详情（轮询接口）
/api/curriculum/{id}/updates/ GET 获取增量更新
/api/curriculum/{id}/cancel/ POST 取消生成
/api/curriculum/{id}/blocks/{block_id}/regenerate/ POST 重新生成 Block

创建教材

创建一个新的 AI 教材生成任务。系统将异步调用 AI 工作流生成教材大纲和内容块。

请求

地址：POST https://test.api.upath.cn/api/curriculum/

请求头：

参数 必填 说明
X-API-Key 是 API 密钥
Content-Type 是 application/json

请求参数：

参数 类型 必填 说明
topic string 是 教材主题，2-500 字符

请求示例：

{
  "topic": "量子力学基础"
}

响应

成功响应（HTTP 201）：

字段 类型 说明
id integer 教材 ID
topic string 用户输入的主题
title string AI 生成的标题（创建时为空）
difficulty string 难度等级（创建时为空）
difficulty_display string 难度中文显示
estimated_time string 预计学习时长（创建时为空）
tags array 标签列表（创建时为空）
status string 状态，固定为 pending
status_display string 状态中文显示
total_blocks integer Block 总数（创建时为 0）
completed_blocks integer 已完成 Block 数（创建时为 0）
progress float 完成百分比（创建时为 0）
version integer 版本号（创建时为 0）
blocks array Block 列表（创建时为空）
created_at string 创建时间
updated_at string 更新时间

并发限制

每个客户同时生成中的教材数量有上限（默认 3 个）。当处于 pending、planning、generating 状态的教材数达到上限时，将返回 HTTP 429 错误。请等待现有教材生成完成后再创建新的教材。

错误码

错误码 HTTP 状态码 说明
InvalidParameter 400 topic 参数为空或超过 500 字符
Unauthorized 401 API Key 无效
TooManyRequests 429 超过并发生成数限制

获取教材列表

获取当前客户的教材列表，支持筛选、搜索和排序。

请求

地址：GET https://test.api.upath.cn/api/curriculum/

请求头：

参数 必填 说明
X-API-Key 是 API 密钥

查询参数：

参数 类型 必填 说明
status string 否 状态筛选（pending/planning/generating/completed/failed）
difficulty string 否 难度筛选（beginner/intermediate/advanced）
created_at__gte datetime 否 创建时间起始
created_at__lte datetime 否 创建时间截止
created_at__date date 否 创建日期精确匹配
search string 否 搜索关键词（匹配 topic 和 title）
ordering string 否 排序字段，如 -created_at（默认按创建时间倒序）
page integer 否 页码，默认 1
page_size integer 否 每页数量，默认 20

响应

成功响应（HTTP 200）：

字段 类型 说明
count integer 总记录数
next string 下一页 URL
previous string 上一页 URL
results array 教材列表

results 中每个教材包含与创建接口相同的字段，但不包含 blocks 详情。

获取教材详情

获取教材的完整信息，包含所有 Block 内容。此接口可用于轮询教材生成进度。

请求

地址：GET https://test.api.upath.cn/api/curriculum/{id}/

请求头：

参数 必填 说明
X-API-Key 是 API 密钥

响应

成功响应（HTTP 200）：

返回教材完整信息，包含 blocks 数组。每个 Block 的字段：

字段 类型 说明
id integer Block ID
order integer 顺序（从 0 开始）
block_type string Block 类型（MD/IMG/VID/BOX）
block_type_display string 类型中文显示
sub_type string 子类型
sub_type_display string 子类型中文显示
status string 状态（pending/processing/completed/failed）
status_display string 状态中文显示
content string 章节文字内容
media_content string 媒体内容（URL/Mermaid 代码/HTML）
media_desc string 媒体描述
content_type string 内容类型（text/url/mermaid/html）
metadata object 元数据
error_message string 错误信息
created_at string 创建时间
started_at string 开始生成时间
completed_at string 完成时间

轮询建议

  • 建议每 2-5 秒轮询一次
  • 当教材 status 为 completed 或 failed 时停止轮询
  • 如需减少数据传输量，推荐使用增量更新接口

错误码

错误码 HTTP 状态码 说明
NotFound 404 教材不存在

获取增量更新

获取教材自指定版本以来的增量更新，仅返回有变化的 Block，减少数据传输量。

请求

地址：GET https://test.api.upath.cn/api/curriculum/{id}/updates/

请求头：

参数 必填 说明
X-API-Key 是 API 密钥

查询参数：

参数 类型 必填 说明
since_version integer 否 上次获取的版本号，默认 0

推荐使用方式

  1. 首次调用教材详情接口获取完整数据，记录 version 值
  2. 后续轮询使用增量更新接口，传入上次的 version
  3. 根据返回的 updated_blocks 局部更新前端数据
  4. 更新本地记录的 version 值

响应

成功响应（HTTP 200）：

字段 类型 说明
version integer 当前版本号
status string 教材状态
status_display string 状态中文显示
completed_blocks integer 已完成 Block 数
updated_blocks array 有更新的 Block 列表

当 since_version 等于当前版本时，updated_blocks 为空数组。

错误码

错误码 HTTP 状态码 说明
NotFound 404 教材不存在

取消生成

取消正在生成中的教材。已完成或已失败的教材无法取消。

请求

地址：POST https://test.api.upath.cn/api/curriculum/{id}/cancel/

请求头：

参数 必填 说明
X-API-Key 是 API 密钥

请求体：无

响应

成功响应（HTTP 200）：

字段 类型 说明
id integer 教材 ID
status string 状态，固定为 failed
message string 固定为 已取消生成

错误码

错误码 HTTP 状态码 说明
InvalidOperation 400 教材已完成或已失败，无法取消
NotFound 404 教材不存在

重新生成 Block

重新生成教材中的某个 Block。正在生成中的 Block 无法重新生成。

请求

地址：POST https://test.api.upath.cn/api/curriculum/{id}/blocks/{block_id}/regenerate/

请求头：

参数 必填 说明
X-API-Key 是 API 密钥

请求体：无

响应

成功响应（HTTP 200）：

字段 类型 说明
id integer Block ID
status string 状态，固定为 pending
message string 固定为 已加入重新生成队列

错误码

错误码 HTTP 状态码 说明
InvalidOperation 400 Block 正在生成中，请稍后再试
NotFound 404 Block 不存在

Block 类型说明

教材由多个 Block 组成，每个 Block 代表一个内容单元。

主类型

block_type 说明 media_content 内容
MD Markdown 文本 无（内容在 content 字段）
IMG 静态图像 图片 URL 或 Mermaid 代码
VID 数学动画 视频 URL
BOX 交互沙盒 HTML 代码

IMG 子类型

IMG 类型的 Block 根据 sub_type 有不同的生成方式：

sub_type 说明 media_content 格式 content_type
PLOT 数据绘图 图片 URL url
DIAGRAM 逻辑图解 Mermaid 代码 mermaid
ILLUSTRATION 叙事插画 图片 URL url
DEFAULT 默认图片 图片 URL url

content_type 字段

通过 Block 的 content_type 字段（位于 metadata 或顶层）判断 media_content 的渲染方式：

  • text：纯文本，直接渲染 Markdown
  • url：媒体文件 URL，使用 <img> 或 <video> 标签渲染
  • mermaid：Mermaid 图表代码，使用 Mermaid.js 渲染
  • html：HTML 代码，使用 <iframe> 沙盒渲染

状态流转

教材状态

stateDiagram-v2
    [*] --> pending: 创建教材
    pending --> planning: 开始规划
    planning --> generating: 大纲生成完成
    generating --> completed: 所有 Block 完成
    generating --> failed: 生成失败
    planning --> failed: 规划失败
    pending --> failed: 用户取消
    planning --> failed: 用户取消
    generating --> failed: 用户取消
状态 说明
pending 待处理，等待异步任务启动
planning 规划中，AI 正在生成教材大纲
generating 生成中，各 Block 正在并发生成
completed 已完成，所有 Block 生成结束
failed 失败，生成出错或用户取消

Block 状态

状态 说明
pending 待处理，等待生成
processing 处理中，AI 正在生成内容
completed 已完成
failed 失败（可通过重新生成接口重试）

使用注意事项

轮询策略

推荐使用增量更新接口进行轮询：

阶段 建议间隔 说明
planning 2 秒 大纲生成通常较快
generating 3-5 秒 Block 生成耗时较长
completed/failed 停止轮询 生成已结束

并发限制

  • 每个客户默认最多同时生成 3 个教材
  • 处于 pending、planning、generating 状态的教材计入并发数
  • 超过限制时创建接口返回 HTTP 429

自动重试

  • Block 生成失败时系统会自动重试，最多 2 次
  • 重试采用指数退避策略（10 秒、20 秒）
  • 重试耗尽后 Block 标记为 failed，不影响其他 Block 生成
  • 失败的 Block 可通过重新生成接口手动重试