生成第一份 PPT （简易版）

这一节介绍便携版接口。它是一套新的上层 API，和原有 docmee.cn 标准版接口分开部署，建议的接入地址如下：


https://open.docmee.cn/v2/api/portable/

便携版的目标是把标准版里的“创建任务 + 生成内容 + 生成 PPT + 获取下载地址”封装成更少的接口，适合直接接收用户输入并输出最终 PPT 的场景。

这个流程里，业务侧只需要关心两件事：

创建任务时传入用户输入、模板 ID 和生成参数
根据 stream 选择“轮询结果”或“SSE 持续接收结果”

如果你需要完整控制每一个中间步骤，请使用完整版。

便携版接口设计

便携版保留 2 种获取结果的方式：

异步任务轮询：创建任务后，轮询结果接口获取最终 PPT
SSE 长连接：创建任务时传 stream=true，持续接收生成进度和最终结果

对应只需要 2 个接口：

第 1 步：创建调用 Token

便携版仍然沿用现有鉴权方式。先在服务端使用 Api-Key 调用 createApiToken。

拿到返回的 token 后，后续请求都在 Header 中传入：


token: YOUR_TEMP_TOKEN

第 2 步：创建便携版任务

调用 POST https://open.docmee.cn/v2/api/portable/create-task 创建任务。

请求方式

创建任务支持两种请求体格式：

Content-Type	适用场景
`application/json`	不需要上传文件时，直接传文本参数
`multipart/form-data`	需要上传参考文件时，使用 `file` 字段

如果当前场景需要上传文件，必须使用 multipart/form-data；如果不需要上传文件，推荐使用更简单的 application/json。

请求参数

便携版的参数设计以 createTask 和 generateContent 的已有能力为基础，只保留上层封装真正需要的字段。

参数	类型	必填	来源	说明
`type`	`1-7`	✅	`createTask`	任务类型。`1` 智能生成；`2` 上传文件；`3` 思维导图；`4` Word 精准转 PPT；`5` 网页链接；`6` 粘贴文本；`7` Markdown 大纲
`content`	`string`	❌	`createTask`	根据 `type` 传主题、网页链接、文本内容或 Markdown
`file`	`File[]`	❌	`createTask`	上传文件时使用，仅 `multipart/form-data` 支持
`templateId`	`string`	✅	便携版新增	指定最终生成 PPT 使用的模板 ID
`stream`	`boolean`	❌	`generateContent`	是否使用 SSE 长连接返回生成过程，默认 `false`
`length`	`short \| medium \| long`	❌	`generateContent`	内容长度偏好
`scene`	`string`	❌	`generateContent`	演示场景，例如“产品介绍”
`audience`	`string`	❌	`generateContent`	受众类型，例如“客户”
`lang`	`string`	❌	`generateContent`	输出语言，例如 `zh`、`en`
`prompt`	`string`	❌	`generateContent`	附加要求，建议保持简短
`useAgent`	`boolean`	❌	-	是否使用智能体生成，默认 `false`

useAgent 仅在任务类型为 1 时生效，其他任务类型会忽略该字段。

useAgent 为 true 时，会使用智能体（智能体会自行思考、搜索、总结）生成内容。

如果您想让大纲效果更好，您可以开启智能体生成，开启后智能体会自行思考、搜索、总结（内容生成更准确，但耗时更长，消耗1积分）。

参数说明

场景	建议传参
智能生成	`type=1`，`content` 传主题或需求描述
上传文件生成	`type=2` 或 `type=4`，通过 `file` 上传原始文件，可附加 `prompt`
网页转 PPT	`type=5`，`content` 传网页链接
粘贴文本生成	`type=6`，`content` 传原始文本
Markdown 大纲生成	`type=7`，`content` 传 Markdown 大纲

prompt 仅在任务类型为 1、2、5、6 时生效，其他任务类型通常会忽略该字段。

响应模式

`stream` 值	响应方式	说明
`false` 或不传	`application/json`	立即返回 `taskId`，后续通过 `taskResult` 轮询
`true`	`text/event-stream`	保持长连接，持续返回进度和最终结果

JSON 请求示例


const response = await fetch('https://open.docmee.cn/v2/api/portable/createTask', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    token: 'YOUR_TEMP_TOKEN'
  },
  body: JSON.stringify({
    type: 1,
    content: '请生成一份关于 AI 办公趋势的产品介绍 PPT',
    templateId: 'TEMPLATE_ID',
    stream: false,
    length: 'medium',
    scene: '产品介绍',
    audience: '客户',
    lang: 'zh',
    prompt: '语气专业，适合演示'
  })
})
 
const result = await response.json()
console.log(result)

FormData 请求示例


const formData = new FormData()
formData.append('type', '2')
formData.append('templateId', 'TEMPLATE_ID')
formData.append('stream', 'false')
formData.append('length', 'medium')
formData.append('scene', '产品介绍')
formData.append('audience', '客户')
formData.append('lang', 'zh')
formData.append('prompt', '请突出重点结论')
formData.append('file', fileInput.files[0])
 
const response = await fetch('https://open.docmee.cn/v2/api/portable/createTask', {
  method: 'POST',
  headers: {
    token: 'YOUR_TEMP_TOKEN'
  },
  body: formData
})
 
const result = await response.json()
console.log(result)

非流式返回示例

当 stream=false 或不传时，接口立即返回任务信息：


{
  "code": 0,
  "data": {
    "taskId": "PORTABLE_TASK_ID",
    "status": "pending",
    "message": "task created"
  }
}

SSE 返回说明

当 stream=true 时，接口返回 text/event-stream，客户端可以持续接收系统当前执行阶段与最终结果。

示例：


event: message
data: {"taskId":"PORTABLE_TASK_ID","status":"processing","step":"create_task","progress":10}

event: message
data: {"taskId":"PORTABLE_TASK_ID","status":"processing","step":"generate_content","progress":55}

event: message
data: {"taskId":"PORTABLE_TASK_ID","status":"processing","step":"generate_ppt","progress":85}

event: message
data: {"taskId":"PORTABLE_TASK_ID","status":"success","progress":100,"pptId":"PPT_ID","fileUrl":"https://example.com/demo.pptx"}

第 3 步：轮询任务结果

如果你没有使用 SSE，或者需要在断线后继续查询任务结果，可以调用：


POST https://open.docmee.cn/v2/api/portable/task-result

请求参数

参数	类型	必填	说明
`taskId`	`string`	是	创建任务后返回的任务 ID

返回字段

字段	说明
`taskId`	任务 ID
`status`	任务状态：`pending`、`processing`、`success`、`failed`
`progress`	当前进度，可选
`step`	当前执行阶段，可选
`pptId`	成功时返回
`fileUrl`	成功时返回，PPT 下载地址
`coverUrl`	成功时返回，封面图地址
`previewUrl`	成功时返回，预览地址
`errorCode`	失败时返回
`errorMessage`	失败时返回


const response = await fetch('https://open.docmee.cn/v2/api/portable/task-result', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    token: 'YOUR_TEMP_TOKEN'
  },
  body: JSON.stringify({
    taskId: 'PORTABLE_TASK_ID'
  })
})
 
const result = await response.json()
console.log(result)

处理中返回示例：


{
  "code": 0,
  "data": {
    "taskId": "PORTABLE_TASK_ID",
    "status": "processing",
    "progress": 65,
    "step": "generate_ppt"
  }
}

成功返回示例：


{
  "code": 0,
  "data": {
    "taskId": "PORTABLE_TASK_ID",
    "status": "success",
    "progress": 100,
    "step": "completed",
    "pptId": "PPT_ID",
    "fileUrl": "https://example.com/demo.pptx",
    "coverUrl": "https://example.com/cover.png",
    "previewUrl": "https://example.com/preview"
  }
}

失败返回示例：


{
  "code": 5001,
  "data": {
    "taskId": "PORTABLE_TASK_ID",
    "status": "failed",
    "errorCode": "TASK_FAILED",
    "errorMessage": "generate ppt failed"
  }
}

简易版与完整版的区别

简易版适合下面这类场景：

你只想接收用户输入，然后拿到最终 PPT 结果
你希望直接使用指定模板生成成品
你希望前端逻辑尽量简单，既可以轮询，也可以直接接 SSE

如果你需要以下能力，请使用完整版：

先生成 Markdown，再让用户手动编辑内容
对内容生成和 PPT 生成做分步控制
在各个阶段插入自定义审核、编辑或重试逻辑

常见建议

没有文件上传时优先用 application/json
需要上传文件时使用 multipart/form-data
建议业务侧保存 taskId，用于断线恢复和失败重试
templateId 建议通过templates提前获取
生产环境由服务端创建 Token，不要在前端暴露 Api-Key