API 总览 - DeckFlow 开发者

接口调用模型

DeckFlow API 采用异步任务模型处理大多数文件操作，其核心流程如下：

身份验证：所有 API 请求均需要在请求头中携带 API 密钥（API key）进行身份校验。
文件上传与导入：支持上传本地文件（支持 PDF、Word、PPTX、Keynote、Excel 等格式），或者提供网页链接（URL）及纯文本输入。
任务创建：调用特定接口（如创建、焕新或翻译）发起异步任务，成功后系统将返回一个唯一的任务 ID（Task ID）。
状态查询与轮询：使用任务 ID 轮询任务的状态与进度，获取当前排队、处理中、成功或失败的反馈。
结果下载：任务成功后，API 将返回临时有效的带签名下载链接，供开发者获取最终生成的演示文稿或处理后的文件。
回调通知 (Webhook)：支持配置 Webhook 回调，在任务状态发生变更（如成功或失败）时由服务器端主动向开发者的系统推送通知。

1. 通用 API 与认证

所有 DeckFlow API 端点的基础路径、认证方式和任务状态流都是统一通用的。

接口 Base URL

所有 API 请求的 Base URL 为：https://app.deckflow.com/api

HTTP 请求头

对于每个 API 请求或文件检索，请包含以下请求头进行认证：

请求头	类型	是否必填	描述
`Authorization`	String	是	格式为 `Bearer <YOUR_API_KEY>` 的 API 密钥。
`Content-Type`	String	是	提交任务时必须设置为 `multipart/form-data`。

2. 提交异步任务

所有任务的提交（包括生成、翻译、焕新以及其他工具 API）均通过单步的 multipart/form-data 格式向统一的任务管理接口提交。无需提前上传文件，只需在请求体中直接传递文件二进制数据和参数即可。

接口地址

路径: POST /tools/tasks
Content-Type: multipart/form-data

请求体参数 (Form Data)

参数名	类型	是否必填	描述
`files`	File	是	待处理的源文件。支持多个文件（例如用于合并任务）。
`type`	String	是	任务类型。例如 `generation` (生成)、`translation` (翻译)、`revamp` (焕新) 或 `convertor.ppt2pdf` (转换)。
`notifyURL`	String	否	接收任务状态更新通知的 Webhook 回调 URL。
`params`	String (JSON)	否	附加选项，以 JSON 字符串形式提供。默认为空 JSON 字符串 `"{}"`。

请求示例

  curl --location 'https://app.deckflow.com/api/tools/tasks' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --form 'files=@"/path/to/presentation.pptx"' \
  --form 'type="convertor.ppt2pdf"' \
  --form 'params="{}"'

  const formData = new FormData();
  formData.append('files', fileInput.files[0]);
  formData.append('type', 'convertor.ppt2pdf');
  formData.append('params', JSON.stringify({}));

  const response = await fetch('https://app.deckflow.com/api/tools/tasks', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <YOUR_API_KEY>'
    },
    body: formData
  });
  const result = await response.json();

  import requests

  url = "https://app.deckflow.com/api/tools/tasks"
  headers = {
      "Authorization": "Bearer <YOUR_API_KEY>"
  }
  files = [
      ("files", ("presentation.pptx", open("presentation.pptx", "rb"), "application/vnd.openxmlformats-officedocument.presentationml.presentation"))
  ]
  data = {
      "type": "convertor.ppt2pdf",
      "params": "{}"
  }

  response = requests.post(url, headers=headers, files=files, data=data)
  print(response.json())

响应体 (JSON)

{
  "id": "task-uuid-string",
  "name": "presentation.pptx",
  "type": "convertor.ppt2pdf",
  "status": "pending",
  "preview": null,
  "createdAt": "2026-06-11T08:52:00.000Z",
  "updatedAt": "2026-06-11T08:52:00.000Z"
}

3. 任务状态与管理

3.1 获取任务状态 / 实时流订阅

获取任务详情，或接收任务处理进度的实时流。

接口地址: GET /tools/tasks/{taskId}
普通轮询响应 (JSON):

返回当前任务状态。当 status 变更为 "completed" 时，result 字段将包含文件的下载链接和元数据。若 status 为 "failed"，可通过 error 字段查看失败原因。

Server-Sent Events (SSE) 实时流订阅:

在接口请求头中添加 response-event-stream: yes，接口将返回 text/event-stream 格式的实时长链接数据流。当状态更新时，服务端会推送 data: { ...taskJSON }，在任务状态到达 "completed" 或 "failed" 时自动关闭链接。

3.2 获取空间历史任务列表

查询当前空间下历史提交过的所有任务。

接口地址: GET /tools/tasks?spaceId={spaceId}&type={taskType}&_startIndex={offset}&_maxResults={limit}
响应头信息:

x-content-record-total 返回当前查询条件下的任务总数。

响应体 (JSON):

包含 Task 实体数组。

3.3 删除任务

删除指定的历史任务，并清理其生成的输出文件。

接口地址: DELETE /tools/tasks/{taskId}
响应状态码: 204 No Content

功能范围与文档依据

核心功能接口：包含创建演示文稿 (Create)、演示文稿焕新 (Revamp) 及文档翻译 (Translate) 的核心 API。
辅助工具接口：提供文件格式转换、内容提取、页面合并与拆分、文件及视频体积压缩优化等 API。
AI 友好文档 (llms.txt): 提供给 LLMs/AI 智能体使用的结构化文档索引，方便智能体快速检索 DeckFlow API 与工具的使用规范。