EduForge AI API 文档

默认 API 基址为 http://localhost:8000。所有业务接口统一返回 JSON 响应信封；生成类接口采用“提交任务 + 查询状态 / SSE 订阅”的异步模型；资源和教材接口则提供同步查询能力，适合工作台页面和校内平台直接接入。

平台支持两类主要调用身份：一类是登录工作台后的教师或管理员，通过 Bearer Token 调用；另一类是第三方系统或自动化服务，通过 X-API-Key 调用。当前公开资源列表不要求鉴权，但工作台生成和管理员治理接口必须校验身份。

从路由组织方式看，接口按业务域划分为认证、生成、资源、教材和管理员治理五大类。集成时建议把“读取元数据”和“触发生成任务”视作两套不同能力：前者偏同步查询，后者偏异步编排，这样更容易在校内平台中设计稳定的交互链路。

对于正式接入，推荐采用统一的错误处理与日志策略：浏览器侧和第三方系统都应首先校验 success，再结合 message、data 或 detail 字段判断后续分支；对异步任务则必须记录 job_id，以便后续查询、审计和问题定位。

所有接口统一采用三段式响应结构：

{
  "success": true,
  "message": "任务状态",
  "data": { ... }
}

其中 success 表示调用是否成功，message 提供当前响应语义，data 存放业务数据。对于校内平台集成而言，推荐始终先判断 success，再按 message 和 data 做业务分流。

需要注意的是，校验失败、权限不足或对象不存在等异常场景可能由 FastAPI 直接返回 detail 字段，而不是 success/message/data 结构。因此调用方应同时兼容两类返回体，而不是假定所有错误都落在同一信封中。

{
  "detail": "章节不存在"
}

Authorization: Bearer <access_token>
X-API-Key: efa_xxxxxxxxxxxxxxxxxxxxxxxx

Bearer Token 适用于教师和管理员在工作台中的请求，由 /api/v1/auth/login 和 /api/v1/auth/register 返回。X-API-Key 适用于自动化系统、校内服务中台或脚本工具，可通过 /api/v1/auth/api-key/regenerate 更新。

当前注册接口会默认创建教师角色账号，并为其生成 API Key。管理员接口则要求管理员身份，因此如果第三方系统需要调用治理能力，建议通过受控后台或中间服务代理，而不是直接暴露管理员凭证。

curl -X POST http://localhost:8000/api/v1/auth/login   -H "Content-Type: application/json"   -d '{
    "email": "teacher@example.com",
    "password": "your_password"
  }'

平台的核心模型包括用户、生成任务、资源、教材版本和章节。用户包含 role、plan、api_key 等字段；生成任务包含 job_id、status、progress、result_url、result_metadata 和 error_message；资源记录则包含 chapter_id、resource_type、title、file_url、view_count 和 download_count 等字段。

章节模型是平台最重要的业务锚点。无论是教师生成任务、资源列表还是管理员上传文件，都最终归属于某一章节。因此集成侧如果希望形成长期可治理的资源库，必须把章节 ID 作为正式参数在业务系统中保留。

如果需要在校内系统中保留完整上下文，建议至少存储 user.id、chapter_id、job_id 和 file_url 四类字段。这样既能支撑后续回查，也能为资源复用、任务审计和治理统计提供可靠主键。

curl -X POST http://localhost:8000/api/v1/generate/react-courseware   -H "Content-Type: application/json"   -H "Authorization: Bearer <token>"   -d '{
    "grade": "七年级",
    "subject": "数学",
    "topic": "一元一次方程",
    "features": ["slider", "animation", "chart"],
    "platform": "standalone",
    "code_style": "typescript",
    "chapter_id": "<chapter_uuid>"
  }'

当请求体包含 chapter_id 时，任务完成后会尝试自动创建对应章节资源记录，并进一步生成资源截图。因此对于希望形成长期资源库的接入场景，强烈建议在生成时始终传递章节标识，而不是只保留 topic 或 scope 文字。

以下目录按业务域给出平台当前主要接口。建议集成方先完成认证、教材元数据和资源查询接入，再根据具体业务场景接入生成任务与管理员治理接口，这样更容易形成渐进式上线节奏。

curl "http://localhost:8000/api/v1/resources?grade_id=7&subject_id=1&version_id=3&resource_type=ppt"

curl -X POST http://localhost:8000/api/v1/admin/resources/upload   -H "Authorization: Bearer <admin_token>"   -F "chapter_id=<chapter_uuid>"   -F "resource_type=other"   -F "title=校本活动案例"   -F "description=用于教研共享"   -F "file=@./case-study.pdf"

{
  "email": "teacher@example.com",
  "password": "StrongPass123",
  "name": "王老师",
  "school_name": "示范中学",
  "subject": "数学",
  "grade_range": "七年级"
}

{
  "success": true,
  "message": "注册成功",
  "data": {
    "access_token": "<jwt>",
    "token_type": "bearer",
    "user": {
      "id": "<user_uuid>",
      "email": "teacher@example.com",
      "role": "teacher",
      "plan": "free",
      "api_key": "efa_xxxxxxxxx"
    }
  }
}

{
  "grade": "七年级",
  "subject": "数学",
  "topic": "有理数加减法",
  "version": "人教版",
  "slides": 12,
  "style": "interactive",
  "inclusions": ["objectives", "content", "examples", "exercises"],
  "output_format": ["pptx"],
  "chapter_id": "<chapter_uuid>"
}

{
  "success": true,
  "message": "PPT 生成任务已提交",
  "data": {
    "job_id": "<job_uuid>",
    "status": "pending",
    "progress": 0,
    "result_url": null,
    "error_message": null
  }
}

{
  "grade": "八年级",
  "subject": "物理",
  "scope": "压强与浮力",
  "version": "人教版",
  "total_questions": 24,
  "difficulty": "balanced",
  "question_types": {
    "single_choice": 10,
    "fill_blank": 8,
    "short_answer": 6
  },
  "include_answers": true,
  "include_rubric": true,
  "include_knowledge_index": true,
  "output_format": "pdf",
  "chapter_id": "<chapter_uuid>"
}

{
  "success": true,
  "message": "试卷生成任务已提交",
  "data": {
    "job_id": "<job_uuid>",
    "status": "pending",
    "progress": 0
  }
}

GET /api/v1/generate/status/<job_uuid>
Authorization: Bearer <access_token>

{
  "success": true,
  "message": "任务状态",
  "data": {
    "job_id": "<job_uuid>",
    "status": "completed",
    "progress": 100,
    "result_url": "/storage/ppt/demo.pptx",
    "result_metadata": {
      "title": "有理数加减法",
      "artifacts": ["/storage/ppt/demo.pptx"]
    },
    "completed_at": "2026-05-06T09:00:00Z"
  }
}

GET /api/v1/resources?grade_id=7&subject_id=1&version_id=3&chapter_id=<chapter_uuid>&resource_type=ppt

{
  "success": true,
  "message": "资源列表",
  "data": [
    {
      "id": "<resource_uuid>",
      "chapter_id": "<chapter_uuid>",
      "resource_type": "ppt",
      "title": "有理数加减法课堂演示",
      "file_url": "/storage/ppt/demo.pptx",
      "thumbnail_url": "/storage/resource-thumbnails/<resource_uuid>.png"
    }
  ]
}

GET /api/v1/textbook/chapters?grade_id=7&subject_id=1&version_id=3&semester=1

{
  "success": true,
  "message": "章节列表",
  "data": [
    {
      "id": "<chapter_uuid>",
      "title": "有理数加减法",
      "short_title": "有理数加减法",
      "order": 3,
      "knowledge_points": ["相反数", "绝对值"],
      "resource_count": 4,
      "semester": 1,
      "publisher": "人教版"
    }
  ]
}

chapter_id=<chapter_uuid>
resource_type=other
title=校本案例汇编
description=用于教研共享
thumbnail_prompt=现代简洁的教学资源封面
file=@./case-study.pdf

{
  "success": true,
  "message": "资源已上传",
  "data": {
    "id": "<resource_uuid>",
    "resource_type": "other",
    "title": "校本案例汇编",
    "file_url": "/storage/resource-library/other/case-study.pdf",
    "thumbnail_url": "/storage/resource-thumbnails/<resource_uuid>.png"
  }
}

认证接口负责建立教师或管理员的正式身份上下文。对于学校接入场景，建议把登录态获取、当前用户读取和 API Key 生命周期管理明确拆开，避免在同一条调用链中混用用户会话和服务凭证。

推荐做法是：用户进入工作台时使用 Bearer Token，服务到服务接入时再单独使用 API Key，并把 API Key 再生动作限制在受控后台或管理员审批流程中。

生成接口全部采用异步任务模型。调用方不应把提交成功等同于生成成功，而应把 job_id 视作正式流程主键，贯穿状态追踪、产物读取、异常告警和后续资源治理。

如果目标是形成长期资源资产，建议在所有生成请求中都传入 chapter_id。这样任务完成后平台可以继续尝试自动入库资源，并接续缩略图生成与公开展示链路。

资源与教材接口承担两个职责：一是为前端筛选器和集成系统提供稳定的章节元数据；二是让正式资源库能按教材维度被检索、展示和复用。实际接入时，建议先接教材接口，再把资源查询接到选中的章节上下文上。

对于资源展示，建议统一以 file_url 和 thumbnail_url 为准，不要在外部系统中硬编码具体目录结构。这样能够同时兼容 AI 自动生成产物和管理员手工上传的长期资源。

管理员接口直接决定章节结构、正式资源、截图质量和站点视觉资产的治理水平。由于这些接口带有明显的发布和维护属性，建议仅向管理员角色或受控中间层开放，不建议直接暴露给普通用户端。

对于资源上传链路，建议在校内制度上同步明确命名规范、截图标准、公开发布责任与审计要求。这样管理员接口才不仅是“可用”，而是真正变成学校资源治理流程的执行入口。

GET /api/v1/generate/stream/{job_id} 采用 text/event-stream 返回任务状态。当前事件体包含 success、status、progress、result_url、metadata 和 error_message 六个核心字段，适合工作台前端或第三方系统做进度条、错误提示和完成后自动下载。

data: {
  "success": true,
  "status": "processing",
  "progress": 56,
  "result_url": null,
  "metadata": null,
  "error_message": null
}

当前服务端会按约 0.6 秒频率推送一次状态，并在任务进入 completed 或 failed 后结束流。客户端实现上建议同时设置超时与兜底轮询逻辑，避免因浏览器休眠、网络代理或 EventSource 中断造成前端状态停滞。

const source = new EventSource('/api/v1/generate/stream/<job_id>')
source.onmessage = (event) => {
  const payload = JSON.parse(event.data)
  if (payload.status === 'completed' || payload.status === 'failed') {
    source.close()
  }
}

平台所有文件资产统一落在 /storage 挂载目录下，通过相对路径回传，例如 /storage/ppt/xxx.pptx、/storage/react-courseware/xxx.tsx、/storage/exam/xxx.pdf。站点案例图、首页展示图和资源截图则统一归档到图片目录，由本地图像 API 或管理员上传生成。

对于资源卡片展示，建议始终优先使用截图或案例图，再暴露下载入口。这样既便于教师快速识别资源内容，也便于管理员在资源库治理时完成视觉审查。PPTX 资产支持调用本机 PowerPoint 协议直接打开，React 课件支持站内运行预览。

调用方不应假定所有资源都来自同一目录，而应以 file_url 和 thumbnail_url 为准进行展示与下载。这样既能兼容 AI 自动生成资源，也能兼容管理员手工上传的长期资产。

对于生成类接口，除 HTTP 状态码外，还应重点关注任务成功创建后返回的 error_message。也就是说，接口层返回 200 只代表任务已被受理，并不意味着最终生成必定成功，真正的业务结果需要通过状态接口或 SSE 继续确认。

NEXTAUTH_SECRET=...
NEXTAUTH_URL=http://localhost:3000
SECRET_KEY=...
DATABASE_URL=mysql+aiomysql://root:***@localhost:3306/eduforge
LLM_PROVIDER=tongyi
LLM_API_KEY=...
LLM_API_URL=https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation
LLM_MODEL=qwen-plus
LOCAL_IMAGE_API_URL=http://localhost:3002
LOCAL_IMAGE_DEFAULT_SIZE=1024*1536
NEXT_PUBLIC_API_URL=http://localhost:8000
INTERNAL_API_URL=http://localhost:8000

其中 LOCAL_IMAGE_API_URL 指向本地图像生成服务，用于首页图片、案例图和资源截图生成；NEXT_PUBLIC_API_URL 与 INTERNAL_API_URL 分别供浏览器侧与服务器侧请求使用。生产环境建议把前后端、数据库、模型密钥和图片服务地址统一交由学校信息中心管理。

如果学校采用前后端分离或反向代理部署，建议先固定 API 基址和静态资源访问策略，再开放给教师和第三方系统使用。这样可以减少前端地址变更、跨域策略调整和外部回调不一致带来的运维成本。

所有受 API Key 调用的接口共享一组配额计数器，按 1 分钟 / 1 小时 / 1 天 / 月度四个维度滚动统计。当任一维度达到阈值时，服务端返回 HTTP 429 与 {"detail": "rate_limited"}，并在响应头 Retry-After 中给出建议重试间隔。

所有响应均会附带以下响应头帮助客户端做退避：X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset (Unix 秒)。建议客户端在收到 429 时使用指数退避，初始 2 秒，最多 5 次重试，并在第 3 次重试时检查是否需要切换备用 API Key。

所有 HTTP 路径以 /api/v1/ 开头。我们承诺在 v1 大版本生命周期内保持以下兼容性：

• 不会移除已有字段；废弃字段会先标记 deprecated 至少 6 个月并在响应头 Sunset 中通告下线时间。
• 不会改变现有字段的类型；仅会新增字段或新增可选请求参数。
• 新增端点会在 API 文档与白皮书的同一日同步发布；破坏性更改将进入下一个大版本 (/api/v2/)。
• SSE 事件名只增不删；新增事件名前会在文档中以 Beta 标记不少于 30 天。

客户端建议在请求头中显式声明可接受的版本范围，例如 Accept: application/vnd.eduforge.v1+json，以便服务端在未来切换默认版本时仍能向后兼容。

下一阶段计划提供 Webhook 推送，便于把生成完成、资源入库、章节调整等关键事件回调到学校自有平台。当前版本仍以 SSE + 轮询为主，下表给出规划中的事件清单与签名机制，便于平台集成方提前规划接入方案。

Webhook 会在请求头中附带 X-EduForge-Signature，使用 HMAC-SHA256 对原始 body 做签名，密钥为接入方在管理员后台登记的 webhook secret。建议接入方对超过 5 分钟的请求视为重放并拒绝处理。

当前版本不强制使用 SDK，所有接口都可使用任意支持 HTTP 与 SSE 的客户端调用。以下示例覆盖最常用的三个动作：申请并使用 API Key、提交 PPT 生成任务、订阅 SSE 进度。

curl -X POST "$API/api/v1/generate/ppt" \
  -H "X-API-Key: $EDUFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chapter_id": "ch_human_geography_01",
    "topic": "城市化与产业升级",
    "objectives": ["理解城市化阶段差异", "掌握产业升级评价指标"],
    "slide_count": 18,
    "language": "zh-CN"
  }'

import httpx

with httpx.stream(
    "GET",
    f"{API}/api/v1/generate/stream/{job_id}",
    headers={"X-API-Key": api_key},
    timeout=None,
) as response:
    for line in response.iter_lines():
        if line.startswith("data:"):
            print(line.removeprefix("data:").strip())

const form = new FormData()
form.append('chapter_id', chapterId)
form.append('resource_type', 'exam_pdf')
form.append('title', '高一地理 · 期中模拟卷')
form.append('file', file)

const created = await fetch(`${API}/api/v1/resources/upload`, {
  method: 'POST',
  headers: { 'X-API-Key': apiKey },
  body: form,
}).then((r) => r.json())

// 缩略图由 LibreOffice + PyMuPDF 异步生成，通常 5 ~ 30 秒可用
const detail = await fetch(`${API}/api/v1/resources/${created.id}`).then((r) => r.json())

如果计划在校内做更深入的二次开发，建议封装统一的请求层，集中处理 API Key 注入、429 退避、SSE 重连和文件下载校验，避免业务模块各自实现造成维护成本上升。

提交技术问题时，建议同时附上请求路径、请求参数、HTTP 状态码、job_id、error_message、目标章节 ID 和相关存储地址。对于管理员治理问题，还应附上资源 ID 或截图更新链路，这样能够显著缩短定位时间。