# DeckFlow Developer Documentation - Full Content Bundle > Contains the full documentation set in both Chinese and English. ========================================= LANGUAGE BUNDLE: ZH ========================================= ## [ZH] API 密钥 **URL:** `https://app.deckflow.com/docs/zh/guide/authentication.md` # API 密钥 > 在设置中生成您的 DeckFlow API 密钥。使用它来对 API 请求、MCP 集成、CLI 工作流和服务器端自动化进行身份验证。 DeckFlow 使用 API 密钥（API key）身份验证来进行开发者访问。密钥绑定到创建它的账户或工作区，使用该密钥的额度消耗将计入对应的账户或工作区。 ## 获取 API 密钥 1. 登录 DeckFlow。 2. 打开[**设置** (Settings)](https://app.deckflow.com/start#settings)。 3. 进入 API 密钥管理页面。 4. 生成或复制您的 API 密钥。 请妥善保管您的密钥。该密钥可用于创建任务、访问工作区资源以及消耗 Credit 和 Spark 额度。 ## 配置您的 API 密钥 ### 环境变量（推荐） ```bash export DECKFLOW_API_KEY="Bearer " export DECKFLOW_API_BASE="https://app.deckflow.com/api" ``` ### .env 文件 如果您的项目使用 `.env` 文件，请将密钥存储在源代码之外： ```text DECKFLOW_API_KEY="Bearer " DECKFLOW_API_BASE=https://app.deckflow.com/api ``` ### MCP 与 CLI 对于 MCP 客户端、本地智能体、CI 任务和 CLI 自动化，请在启动工作流之前设置 `DECKFLOW_API_KEY` 环境变量。 ```bash export DECKFLOW_API_KEY="Bearer " # Start your MCP client, CLI command, or agent process after this. ``` 在 CI 环境中，请将密钥存储在服务商提供的机密管理器（Secret Manager）中。请勿将 API 密钥直接写入提示词、Notebook（如 Jupyter）、已提交的配置文件或纯前端浏览器代码中。 ## 在请求中携带密钥 所有 DeckFlow API 请求均通过 `Authorization` 请求头进行身份验证。 ```bash curl -X POST "$DECKFLOW_API_BASE/tools/tasks" \ -H "Authorization: $DECKFLOW_API_KEY" ``` ```javascript const response = await fetch(`${process.env.DECKFLOW_API_BASE}/tools/tasks`, { method: "POST", headers: { "Authorization": process.env.DECKFLOW_API_KEY }, }); ``` ```python import os, requests response = requests.post( f"{os.environ['DECKFLOW_API_BASE']}/tools/tasks", headers={"Authorization": os.environ["DECKFLOW_API_KEY"]}, timeout=60, ) ``` ## 密钥范围与计费 API 请求所产生的额度消耗将直接计入与该 API 密钥关联的账户或工作区。如果服务器、CI 任务、MCP 客户端或 CLI 脚本使用该密钥，则这些环境启动的所有任务都将消耗相同的工作区配额。 有关配额扣减规则和计费详情，请参阅[定价与计费](./pricing-billing.md)。 ## 常见错误排查 | 状态码 | 含义 | 推荐排查方案 | | --- | --- | --- | | `401` | 密钥缺失、无效、已过期，或使用了错误的 Header。 | 确认 `Authorization` 请求头，并从[设置](https://app.deckflow.com/start#settings)页面重新复制密钥。 | | `403` | 密钥有效，但无权访问请求的工作区、功能或资源。 | 检查工作区成员资格、套餐权限和功能可用性。 | | `429` | 密钥有效，但账户消耗超出了速率限制或配额上限。 | 降低请求并发或等待额度自动恢复。 | ## 安全最佳实践 - **切勿将 API 密钥提交到版本控制系统中。** 请将 `.env` 添加到 `.gitignore` 中。 - **切勿在客户端或浏览器代码中直接暴露密钥。** 应当从后端或受信任的自动化环境中调用 DeckFlow。 - **定期轮换或重新生成密钥。** 当团队人员变动、服务器更换或密钥可能泄露时，应在[设置](https://app.deckflow.com/start#settings)页面重新生成密钥。 - **在设置中监控额度与使用情况。** 定期查看配额消耗，排查是否存在异常任务或非预期流量。 --- ## [ZH] 核心概念 **URL:** `https://app.deckflow.com/docs/zh/guide/core-concepts.md` # 核心概念 > DeckFlow 开发者平台的核心架构、三大产品工作流及领域实体模型的详细介绍。 DeckFlow 提供了强大的幻灯片文档自动生成、处理与优化能力。所有接口均统一在基础 Base URL `https://app.deckflow.com/api` 之下，并通过统一的 HTTP 请求头认证机制进行授权调用。 ## 1. 主要产品工作流 DeckFlow 包含三大核心业务工作流，并附带一组独立的文件处理工具： ### 提交生成任务 (Create) 从多种类型的输入源智能生成全新、专业的幻灯片（PPTX）： - **输入源类型**：本地源文档（如 PDF、Word、Markdown）、网页链接（URL）或文本主题提示词（Prompt）。 - **参数控制**：可通过参数指定页数（`pageCount`）、长宽比（`aspect ratio`）、目标受众、作者，并控制是否启用网络搜索（`enableSearch`）或高级推理模型（`advancedModel`）。 ### 提交焕新任务 (Revamp) 在完全保留源文稿数据、文本、数据结构与顺序的前提下，重新设计现有演示文稿的视觉外观： - **输入文件**：支持上传 PPTX、Keynote、PDF 格式文稿。 - **视觉风格**：支持套用企业自定义的 **品牌 DNA** 配置文件或内置专业设计模版。 ### 提交翻译任务 (Translate) 对文稿或办公文档进行多语言翻译，并在翻译后完美保持文稿原有的排版版面与字体动画： - **输入文件**：支持 PPTX、Keynote、PDF、Word、Excel 格式。 - **自定义选项**：支持应用企业专属的 **术语表 (Glossary)**，确保专业名词的精准翻译。 ## 2. 核心实体模型 ### 异步任务 (Task) 由于文件处理与大模型生成属于重型计算，DeckFlow 全面采用异步任务驱动模型： 1. **任务创建**：通过 `POST /tools/tasks` 接口提交源文件和参数，请求会立即返回，并提供一个唯一的任务标识符 `taskId`。 2. **状态轮询**：开发者通过 `GET /tools/tasks/{taskId}` 接口查询任务详情，或通过长连接实时接收任务进度状态。 3. **状态生命周期**： - `queued`（已排队）：等待后台队列分配计算资源。 - `running`（处理中）：后台引擎正在解析、生成或优化文件。 - `completed`（已成功）：任务成功完成，可以通过 `result.url` 获取下载链接。 - `failed`（已失败）：任务失败，可以通过 `error` 结构体查看具体错误码与排查方案。 ### 配额计费 (Quotas) DeckFlow 使用双币种配额计费模式： - **Credit**：用于标准计算工作，包括 OCR 文本识别、文件格式转换、版式解析和普通的幻灯片生成/翻译。 - **Spark**：用于重型或高级计算工作，包括视频压缩、高级推理大模型生成和超大文件处理。 ### 品牌 DNA (Brand DNA) 品牌 DNA 是工作空间内的全局设计规范配置文件。它定义了品牌专属的调色板、字体库、排版间距及特有的背景布局，被广泛用于 `Create` 和 `Revamp` 工作流中。 ### 术语表 (Glossary) 术语表用于在 `Translate` 工作流中实现精细化的专有名词与品牌词匹配。用户可以预先上传特定领域的术语对，翻译引擎将在翻译过程中强制应用这些术语，从而避免译名不准确。 --- ## [ZH] 示例 **URL:** `https://app.deckflow.com/docs/zh/guide/examples.md` # 示例 > 包含可运行的 API、CLI 和 MCP 代码示例，帮助您快速上手 DeckFlow 后端开发。 以下示例均基于统一的基础地址 `https://app.deckflow.com/api` 及请求头认证机制 `Authorization: Bearer `。 ## 1. API 集成示例 通过 HTTP API 进行异步任务的提交与轮询。以下示例展示了提交一个文档生成任务，并循环轮询状态直到获取下载链接。 ```javascript const API_KEY = "Bearer "; const BASE_URL = "https://app.deckflow.com/api"; async function generateDeck() { const formData = new FormData(); formData.append("type", "generation"); formData.append("params", JSON.stringify({ inputText: "生成一份关于可再生能源市场趋势的研究报告", pageCount: 10 })); // 1. 提交生成任务 const res = await fetch(`${BASE_URL}/tools/tasks`, { method: "POST", headers: { "Authorization": API_KEY }, body: formData }); const task = await res.json(); console.log("任务已提交，任务 ID:", task.id); // 2. 轮询任务状态 const pollInterval = setInterval(async () => { const statusRes = await fetch(`${BASE_URL}/tools/tasks/${task.id}`, { headers: { "Authorization": API_KEY } }); const currentTask = await statusRes.json(); console.log("当前任务状态:", currentTask.status); if (currentTask.status === "completed") { clearInterval(pollInterval); console.log("任务成功！下载链接:", currentTask.result.url); } else if (currentTask.status === "failed") { clearInterval(pollInterval); console.error("任务失败，错误原因:", currentTask.error.message); } }, 5000); } generateDeck(); ``` ```python import time import requests API_KEY = "Bearer " BASE_URL = "https://app.deckflow.com/api" def generate_deck(): headers = { "Authorization": API_KEY } data = { "type": "generation", "params": '{"inputText": "生成一份关于可再生能源市场趋势的研究报告", "pageCount": 10}' } # 1. 提交生成任务 response = requests.post(f"{BASE_URL}/tools/tasks", headers=headers, data=data) task = response.json() task_id = task["id"] print(f"任务已提交，任务 ID: {task_id}") # 2. 轮询任务状态 while True: status_response = requests.get(f"{BASE_URL}/tools/tasks/{task_id}", headers=headers) current_task = status_response.json() status = current_task["status"] print(f"当前任务状态: {status}") if status == "completed": print(f"任务成功！下载链接: {current_task['result']['url']}") break elif status == "failed": print(f"任务失败，错误原因: {current_task['error']['message']}") break time.sleep(5) generate_deck() ``` ## 2. CLI (DeckOps) 自动化示例 `DeckOps` 是负责 DeckFlow 云端处理的任务命令行工具。您可以通过 CLI 快速配置并调用云端服务。 ### 安装与配置 ```bash # 克隆并全局链接 CLI 目录 (以本地开发包为例) git clone https://github.com/deckflow/deckops.git cd deckops npm install npm link # 配置您的 API 密钥和云端基准地址 deckops config set-token "Bearer " deckops config set-api-base "https://app.deckflow.com/api" ``` ### 命令调用示例 ```bash # 提交并运行幻灯片生成任务 deckops create --params '{"inputText":"人工智能在医疗领域的发展","pageCount":8}' # 提交翻译任务并等待结果 (Translate) deckops translate source_presentation.pptx --from zh --to en --timeout 180 # 运行文件压缩优化任务并获取输出 deckops compress large_archive.zip ``` ## 3. MCP 智能体集成示例 在您的 AI 智能体（如 Claude Desktop）中集成 DeckFlow MCP 服务器，可让大模型自动调用文件优化、提取及生成接口。 ### 配置文件定义 在您的桌面版配置文件中添加 DeckFlow 服务器配置： - **macOS 路径**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows 路径**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "deckflow": { "command": "node", "args": ["/Users/tong/Downloads/Dev-Docs/heygen-docs/mcp-server/dist/index.js"], "env": { "DECKFLOW_API_KEY": "Bearer " } } } } ``` 配置完成后，重新启动 Claude Desktop 即可在会话内直接让 Claude 执行文件处理任务。 --- ## [ZH] 限制与错误 **URL:** `https://app.deckflow.com/docs/zh/guide/limits-errors.md` # 限制与错误 > DeckFlow 开发者平台的文件大小限制、API 错误状态码定义及故障重试策略。 为保证计算资源的公平分配和后端服务的稳定性，DeckFlow 对文件处理、接口调用频率和配额做出了明确的限制。 ## 1. 文件大小限制 不同接口与工具所支持的最大单文件大小限制如下。在调用任务创建接口前，请确保文件未超出以下阈值： | 功能 / 工具分类 | 最大单文件大小 | 支持的输入格式 | | --- | --- | --- | | **文档翻译 (Translate)** | **500 MB** | `.pptx`, `.key`, `.pdf`, `.docx`, `.doc`, `.xlsx`, `.xls` | | **网页打包工具 (HTML Player Pack)** | **50 MB** | `.html`, `.htm` | | **HTML 转换器 (html2png / html2pptx)** | **50 MB** | `.html`, `.htm` (支持粘贴 HTML 代码) | | **Markdown 转换器 (markdown2png)** | **10 MB** | `.md`, `.markdown` (支持粘贴 Markdown 文本) | | **图片 OCR 识别 (image.ocr)** | **50 MB** | `image/*` (如 JPG, PNG 等) | | **图片尺寸修改 (image.resize)** | **100 MB** | `image/*` (如 JPG, PNG 等) | | **图片转 WebP (image.convertWebp)** | **100 MB** | `image/*` (如 JPG, PNG 等) | | **视频压缩工具 (video.compress)** | **300 MB** | `video/*` (如 MP4, MOV 等) | | **其他文档与演示文稿工具** | **300 MB** | `.pptx`, `.ppt`, `.key`, `.docx`, `.doc`, `.xlsx`, `.xls`, `.pdf`, `.zip` | ## 2. API 错误状态码 当 API 请求失败或创建任务报错时，接口将返回对应的 HTTP 状态码及 JSON 格式的错误详情。以下为系统通用的状态码规范： | 状态码 | 错误代码 (code) | 描述 / 场景 | 推荐排查与故障恢复方案 | | --- | --- | --- | --- | | `400` | `invalid_parameter` | 请求参数缺失、值格式错误或不支持的文件格式。 | 检查并修正 `POST /tools/tasks` 中的 `type` 或 `params` 属性。 | | `400` | `file_size_exceeded` | 上传的文件超出了上述单文件大小限制。 | 压缩文件体积，或分批次拆分文稿后重新提交。 | | `401` | `unauthorized` | 缺少认证密钥，或 `Authorization` 头部格式不正确。 | 确认请求头格式为 `Authorization: Bearer `。 | | `402` | `insufficient_quota` | 工作区内的 Credit 或 Spark 配额已用尽。 | 提示用户登录 DeckFlow 设置页面补充额度或升级套餐。 | | `403` | `forbidden` | 密钥有效，但无权访问当前工作区、功能或目标 Space。 | 确认 `spaceId` 参数正确，并检查当前密钥的权限范围。 | | `429` | `rate_limit_exceeded` | 接口并发调用超出了速率限制阈值。 | 实施客户端指数退避（Exponential Backoff）重试，降低请求并发。 | | `5xx` | `internal_error` | 服务器内部故障或临时网络错误。 | 可直接进行退避重试。 | ## 3. 任务重试策略 在程序处理 DeckFlow 后端响应时，请遵循以下重试逻辑： - **可重试错误**： - HTTP `429` (限流)：应等待并实施退避重试。 - HTTP `5xx` (服务器临时故障)：建议在短时间延迟后自动重试。 - **不可重试错误**： - HTTP `400` / `401` / `403`：通常是参数、授权或权限问题，重复请求将返回相同结果。必须在修改请求或修复权限后再重试。 - HTTP `402` (配额耗尽)：必须在账户充值或购买配额后重新调用。 --- ## [ZH] 定价与计费 **URL:** `https://app.deckflow.com/docs/zh/guide/pricing-billing.md` # 定价与计费 > 了解 DeckFlow 开发者使用额度的消耗方式。在运行转换、提取、压缩和优化任务前，预估 Tools 任务成本。 DeckFlow 开发者用量计费基于与 API 密钥关联的账户或工作区。Tools 用量使用两种配额货币计量：`credit` 和 `spark`。 ## 计费原理 每个 Tools 任务可能包含固定基础费用和按量计费两部分： ```text 总费用 = baseFee + meteredUnits * meterFee.unitPrice ``` 如果一个工具同时使用 `credit` 和 `spark`，DeckFlow 将分别扣减两种货币。例如，压缩任务可能以 `spark` 计收启动费，再以 `credit` 按文件大小计量。 > API 密钥计费： 用量将计入拥有该 API 密钥的账户或工作区。服务器任务、MCP 调用、CLI 运行和 CI 自动化使用同一密钥时，均消耗相同工作区的配额。 ## Credit 与 Spark | 单位 | 用途 | | --- | --- | | `credit` | 标准处理工作，包括 OCR、幻灯片操作、格式转换、图片调整大小，以及大多数基于页面或文本的工具。 | | `spark` | 更重型或高级工作，包括压缩和面向视频的处理。部分工具仅收取 Spark 基础费，其他工具也以 Spark 计量。 | ## 计量单位 | 计量器 | 含义 | | --- | --- | | `size_10mb` | 以 10 MB 为单位计量文件大小。 | | `text_1k` | 以 1,000 个字符为单位计量文本长度。 | | `page_1` | 以单页/单张幻灯片为单位计量页数。 | 最终扣费金额基于服务器实测的文件大小、文本长度或页数。建议在提交大型任务前显示估算费用，任务完成后使用响应数据展示最终配额消耗。 ## 工具定价 ### 压缩工具 | 工具 | 基础费用 | 计量费用 | | --- | --- | --- | | `file.compress` | `1 spark` | `2 credit / size_10mb` | | `video.compress` | `1 spark` | `2 credit / size_10mb` | ### 图片与 OCR | 工具 | 基础费用 | 计量费用 | | --- | --- | --- | | `image.ocr` | `1 credit` | `1 credit / page_1` | | `image.convertWebp` | `1 credit` | `2 credit / page_1` | | `image.resize` | `1 credit` | `2 credit / page_1` | ### PPTX 工具 | 工具 | 基础费用 | 计量费用 | | --- | --- | --- | | `pptx.split` | `1 credit` | `2 credit / page_1` | | `pptx.join` | `1 credit` | `2 credit / page_1` | | `pptx.getFontInfo` | `1 credit` | `1 credit / page_1` | | `pptx.embedFonts` | `1 spark` | `1 credit / page_1` | ### 文件转换 | 工具 | 基础费用 | 计量费用 | | --- | --- | --- | | `convertor.ppt2image` | `2 credit` | `2 credit / page_1` | | `convertor.ppt2pptx` | `2 credit` | `2 credit / page_1` | | `convertor.ppt2pdf` | `2 credit` | `2 credit / page_1` | | `convertor.doc2pdf` | `1 credit` | `2 credit / page_1` | | `convertor.ppt2video` | `1 spark` | `1 spark / page_1` | | `convertor.pdf2image` | `1 credit` | `1 credit / page_1` | | `convertor.keynote2image` | `3 credit` | `2 credit / page_1` | | `convertor.keynote2html` | `3 credit` | `2 credit / page_1` | | `convertor.keynote2pdf` | `3 credit` | `2 credit / page_1` | | `convertor.html2pptx` | `3 credit` | `2 credit / page_1` | ### HTML 与 Markdown 渲染 | 工具 | 基础费用 | 计量费用 | | --- | --- | --- | | `convertor.html2png` | `1 credit` | `2 credit / text_1k` | | `convertor.markdown2png` | `1 credit` | `2 credit / text_1k` | ## 计费示例 ### 压缩一个 24 MB 文件 `file.compress` 收取 `1 spark` 基础费，再按每 10 MB 收取 `2 credit`。文件按 3 个计量单位计算： ```text 1 spark + (3 × 2 credit) = 1 spark + 6 credit ``` ### 将 12 页 PPT 转为 PDF `convertor.ppt2pdf` 收取 `2 credit` 基础费，再按每页收取 `2 credit`： ```text 2 credit + (12 × 2 credit) = 26 credit ``` ### 将 10 页 PPT 转为视频 `convertor.ppt2video` 的基础费和页数计量均使用 Spark： ```text 1 spark + (10 × 1 spark) = 11 spark ``` ## API 响应中的配额信息 Tasks 响应应在任务接受或完成时包含配额用量。使用这些字段向用户显示清晰的消费明细。 ```json { "quota_usage": { "credits_used": 26, "sparks_used": 0, "remaining_credits": 974, "remaining_sparks": 100 } } ``` > **WARNING** > 工作区配额不足： 如果工作区配额不足，DeckFlow 将在任务处理前予以拒绝。若收到配额不足的错误响应，请勿在代码循环中高频重试；建议直接提示用户补充配额、升级套餐或减小任务规模。 --- ## [ZH] 快速开始 **URL:** `https://app.deckflow.com/docs/zh/guide/quick-start.md` # 快速开始 > DeckFlow 开发者快速入门指南，带您一步步完成 API 密钥配置、任务提交、状态获取的最短调用路径。 DeckFlow API 采用异步任务模型处理大多数文件操作，支持多种文档与演示文稿的翻译、焕新和生成。 ## 核心步骤 ### 步骤 1：获取并配置 API 密钥 在开始之前，请登录 DeckFlow，在设置页面生成您的 API 密钥（API Key）。 配置环境变量以开始使用： ```bash # 配置 API 密钥和基础路径 export DECKFLOW_API_KEY="Bearer " export DECKFLOW_API_BASE="https://app.deckflow.com/api" ``` 详细说明请参阅 [API 密钥](./authentication.md)。 ### 步骤 2：提交任务 所有的任务提交（包括生成、翻译、焕新以及其他工具 API）均通过单步的 `multipart/form-data` 格式向统一的任务管理接口提交。无需提前上传文件，只需在请求体中直接传递文件二进制数据和参数即可。 - **请求路径**：`POST /tools/tasks` - **请求头**： - `Authorization`: `Bearer ` - `Content-Type`: `multipart/form-data` - **主要参数**： - `files`：本地文件。 - `type`：任务类型，例如 `translation`。 - `params`：JSON 字符串。例如 `{"from":"zh","to":"en"}`。 以下为提交翻译任务的代码示例： ```bash curl -X POST "$DECKFLOW_API_BASE/tools/tasks" \ -H "Authorization: $DECKFLOW_API_KEY" \ --form 'files=@"/path/to/presentation.pptx"' \ --form 'type="translation"' \ --form 'params="{\"from\":\"zh\",\"to\":\"en\"}"' ``` ```javascript const formData = new FormData(); formData.append('files', fileInput.files[0]); // 本地 PPTX/PDF/Word 文件 formData.append('type', 'translation'); formData.append('params', JSON.stringify({ from: 'zh', to: 'en' })); const response = await fetch(`${process.env.DECKFLOW_API_BASE}/tools/tasks`, { method: 'POST', headers: { 'Authorization': process.env.DECKFLOW_API_KEY }, body: formData }); const task = await response.json(); console.log('创建的任务:', task); ``` ```python import os, requests url = f"{os.environ['DECKFLOW_API_BASE']}/tools/tasks" headers = { "Authorization": os.environ["DECKFLOW_API_KEY"] } files = [ ("files", ("presentation.pptx", open("presentation.pptx", "rb"), "application/vnd.openxmlformats-officedocument.presentationml.presentation")) ] data = { "type": "translation", "params": '{"from":"zh","to":"en"}' } response = requests.post(url, headers=headers, files=files, data=data) print('创建的任务:', response.json()) ``` 任务创建成功后，将返回包含 `id`（即 `taskId`）和 `"status": "pending"` 的 JSON 响应。 ### 步骤 3：获取任务状态与结果 由于文档处理需要一定时间，您需要使用 `taskId` 来获取处理状态。DeckFlow 提供**轮询（Polling）**和**单步长连接（SSE 订阅）**两种获取状态与结果的方式。 - **请求路径**：`GET /tools/tasks/{taskId}` #### 方式 A：定期轮询 (Polling) 客户端定期（如每隔 3-5 秒）发送 GET 请求查询状态，直到 `status` 变更为 `completed`（成功）或 `failed`（失败）。 ```bash curl -X GET "$DECKFLOW_API_BASE/tools/tasks/YOUR_TASK_ID" \ -H "Authorization: $DECKFLOW_API_KEY" ``` ```javascript // 简易轮询函数 async function pollTask(taskId) { const url = `${process.env.DECKFLOW_API_BASE}/tools/tasks/${taskId}`; const headers = { 'Authorization': process.env.DECKFLOW_API_KEY }; while (true) { const res = await fetch(url, { headers }); const task = await res.json(); console.log('当前状态:', task.status); if (task.status === 'completed') { console.log('任务成功，结果下载链接:', task.result.url); break; } else if (task.status === 'failed') { console.error('任务失败，原因:', task.error); break; } await new Promise(resolve => setTimeout(resolve, 3000)); // 等待 3 秒后重试 } } ``` ```python import os, requests, time def poll_task(task_id): url = f"{os.environ['DECKFLOW_API_BASE']}/tools/tasks/{task_id}" headers = { "Authorization": os.environ["DECKFLOW_API_KEY"] } while True: response = requests.get(url, headers=headers) task = response.json() status = task.get("status") print("当前状态:", status) if status == "completed": print("任务成功，结果下载链接:", task["result"]["url"]) break elif status == "failed": print("任务失败，原因:", task.get("error")) break time.sleep(3) ``` #### 方式 B：单步长连接 (SSE 订阅) 在 GET 请求中携带请求头 `response-event-stream: yes`，DeckFlow 将会以 `Server-Sent Events (SSE)` 协议返回一个实时长连接。当任务进度或状态更新时，服务端会主动推送事件。任务完成后连接会自动断开，无需多次发起 HTTP 请求。 ```bash curl -X GET "$DECKFLOW_API_BASE/tools/tasks/YOUR_TASK_ID" \ -H "Authorization: $DECKFLOW_API_KEY" \ -H "response-event-stream: yes" ``` ```javascript // 在 Node.js 中使用长连接接收 SSE 实时更新 const url = `${process.env.DECKFLOW_API_BASE}/tools/tasks/${taskId}`; const response = await fetch(url, { headers: { 'Authorization': process.env.DECKFLOW_API_KEY, 'response-event-stream': 'yes' } }); const reader = response.body.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const chunk = decoder.decode(value); // 处理 SSE 的 "data: {...}" 消息帧 const lines = chunk.split('\n'); for (const line of lines) { if (line.startsWith('data:')) { const taskJSON = JSON.parse(line.replace('data:', '').trim()); console.log('收到状态更新推送:', taskJSON.status); if (taskJSON.status === 'completed' || taskJSON.status === 'failed') { console.log('最终结果:', taskJSON); return; } } } } ``` ```python import os, requests, json url = f"{os.environ['DECKFLOW_API_BASE']}/tools/tasks/{task_id}" headers = { "Authorization": os.environ["DECKFLOW_API_KEY"], "response-event-stream": "yes" } # 建立长连接流式接收数据 response = requests.get(url, headers=headers, stream=True) for line in response.iter_lines(): if line: decoded_line = line.decode('utf-8') if decoded_line.startswith('data:'): task_json = json.loads(decoded_line.replace('data:', '').strip()) print("收到状态更新推送:", task_json.get("status")) if task_json.get("status") in ["completed", "failed"]: print("最终结果:", task_json) break ``` ### 步骤 4：下载结果 当状态变更为 `completed` 后，从 `result.url` 获取已处理文件的临时签名下载链接，并将文件下载保存至您的本地。 > **NOTE** > 临时签名 URL 具有有效期限制。如需长久保存处理完成的文件，请务必在链接过期前将文件下载并转存到您自己的存储服务或数据库中。 --- ## [ZH] Webhook / 异步任务与实时订阅 **URL:** `https://app.deckflow.com/docs/zh/guide/webhooks-async-jobs.md` # Webhook / 异步任务与实时订阅 > DeckFlow 异步任务模型、状态订阅方式（SSE 实时流与 API 轮询）及 Webhook 回调机制的优缺点与代码实现。 DeckFlow 的大多数文稿处理操作（包括生成、翻译、焕新以及文件转换）均属于计算密集型任务。为了保证接口的即时响应，DeckFlow 全面采用异步处理模型。 在提交任务（`POST /tools/tasks`）后，开发者可以通过三种不同的方式获取任务的最终结果：**SSE 实时订阅 (Server-Sent Events)**、**定期轮询 (Polling)** 和 **Webhook 回调 (Webhook Callback)**。 ## 1. 状态获取方式对比 为方便开发者选择，以下为 SSE 实时流订阅与定期轮询两种主要拉取方式的优缺点对比： | 获取方式 | 推荐度 | 优点 | 缺点 | 适用场景 | | --- | --- | --- | --- | --- | | **SSE 实时流订阅 (Server-Sent Events)** | **推荐 (Highly Recommended)** | 实时性极高；轻量级且极省资源（单次 HTTP 连接）；无需多次重复建连，服务端主动推送进度。 | 客户端需支持流式响应解析；在长时间断网时需要自行实现重连逻辑。 | 网页/客户端交互、CLI 自动化脚本、要求实时呈现进度的前后台交互。 | | **API 定期轮询 (Polling)** | **仅作为备用 / 降级方案** | 实现简单，任何 HTTP 客户端均原生支持；对客户端环境无特殊流式处理要求。 | 延迟较高；频繁请求会消耗大量网络带宽和服务器计算资源，极易触发 `429` 限流。 | 简单后台定时任务、客户端无法维持长连接的受限环境。 | ## 2. 单步长连接实时订阅 (SSE) 当客户端向任务状态查询接口发送请求时，如果携带了特定的 HTTP 头部，DeckFlow 会自动将连接升级为 SSE 实时数据流。 ### 接口规范 - **请求路径**：`GET /tools/tasks/{taskId}` - **关键请求头**：`response-event-stream: yes` (必须设置为 `yes` 以启用 SSE 模式) ### 代码示例 ```bash # 使用 curl 接收实时状态流推送 curl -X GET "https://app.deckflow.com/api/tools/tasks/YOUR_TASK_ID" \ -H "Authorization: Bearer " \ -H "response-event-stream: yes" ``` ```javascript const taskId = "YOUR_TASK_ID"; const url = `https://app.deckflow.com/api/tools/tasks/${taskId}`; async function subscribeTaskSSE() { const response = await fetch(url, { headers: { 'Authorization': 'Bearer ', 'response-event-stream': 'yes' } }); const reader = response.body.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const chunk = decoder.decode(value); const lines = chunk.split('\n'); for (const line of lines) { if (line.startsWith('data:')) { const task = JSON.parse(line.replace('data:', '').trim()); console.log('收到实时进度推送:', task.status); if (task.status === 'completed') { console.log('任务已完成！下载链接:', task.result.url); return; } else if (task.status === 'failed') { console.error('任务处理失败，错误信息:', task.error); return; } } } } } subscribeTaskSSE(); ``` ```python import requests, json task_id = "YOUR_TASK_ID" url = f"https://app.deckflow.com/api/tools/tasks/{task_id}" headers = { "Authorization": "Bearer ", "response-event-stream": "yes" } def subscribe_task_sse(): response = requests.get(url, headers=headers, stream=True) for line in response.iter_lines(): if line: decoded_line = line.decode('utf-8') if decoded_line.startswith('data:'): task = json.loads(decoded_line.replace('data:', '').strip()) print("收到实时进度推送:", task.get("status")) if task.get("status") == "completed": print("任务已完成！下载链接:", task["result"]["url"]) break elif task.get("status") == "failed": print("任务处理失败，错误信息:", task.get("error")) break subscribe_task_sse() ``` ## 3. 定期轮询机制 (Polling) 若采用轮询机制，客户端必须向状态查询接口发起多次独立的 HTTP 请求。 ### 接口规范 - **请求路径**：`GET /tools/tasks/{taskId}` - **关键请求头**：`Authorization: Bearer ` ### 轮询实现建议 为避免触发服务器的并发限制（`429 Rate Limit`），请务必遵守以下原则： 1. **指数退避**：初始间隔可以设置在 3 秒左右。随着查询次数增加，应逐渐加大间隔（例如 3s -> 5s -> 10s -> 20s），直至任务结束。 2. **硬性超时限制**：建议根据任务文件大小设置最大轮询时长限制（如不超过 5 分钟），超时后标记为轮询终止或重试。 ### 代码示例 ```javascript const taskId = "YOUR_TASK_ID"; const url = `https://app.deckflow.com/api/tools/tasks/${taskId}`; const headers = { 'Authorization': 'Bearer ' }; async function pollTaskStatus() { let delay = 3000; // 初始延迟 3 秒 const maxDelay = 30000; // 最大延迟 30 秒 while (true) { const res = await fetch(url, { headers }); const task = await res.json(); console.log('轮询查询状态:', task.status); if (task.status === 'completed') { console.log('任务成功，结果下载链接:', task.result.url); break; } else if (task.status === 'failed') { console.error('任务失败，原因为:', task.error); break; } // 指数退避累加 await new Promise(resolve => setTimeout(resolve, delay)); delay = Math.min(delay * 1.5, maxDelay); } } pollTaskStatus(); ``` ```python import requests, time task_id = "YOUR_TASK_ID" url = f"https://app.deckflow.com/api/tools/tasks/{task_id}" headers = { "Authorization": "Bearer " } def poll_task_status(): delay = 3.0 # 初始 3 秒 max_delay = 30.0 while True: response = requests.get(url, headers=headers) task = response.json() status = task.get("status") print("轮询查询状态:", status) if status == "completed": print("任务成功，结果下载链接:", task["result"]["url"]) break elif status == "failed": print("任务失败，原因为:", task.get("error")) break time.sleep(delay) delay = min(delay * 1.5, max_delay) poll_task_status() ``` ## 4. Webhook 回调通知 在不想主动订阅或轮询的场景下（例如纯后端离线任务批量处理），DeckFlow 支持通过 HTTP 回调将状态直接推送至开发者的公开服务器。 ### 配置方式 在提交任务（`POST /tools/tasks`）的 Form Data 中，传递 `notifyURL` 参数，内容为您能够接收 POST 请求的公网 HTTP 服务器端点。 ### 回调触发与内容 当任务状态发生终态变化（变更为 `completed` 或 `failed`）时，DeckFlow 平台会自动发起一次 HTTP `POST` 请求。 - **请求体格式**：`application/json` - **请求体内容**：完整的 Task 实体对象 JSON。 #### 回调请求 JSON 示例： ```json { "id": "task-550e8400-e29b-41d4-a716-446655440000", "name": "Market Research Slide Revamp", "type": "revamp", "status": "completed", "result": { "url": "https://app.deckflow.com/download/processed-presentation.pptx?...", "mimeType": "application/vnd.openxmlformats-officedocument.presentationml.presentation" }, "createdAt": "2026-06-11T08:52:00.000Z", "updatedAt": "2026-06-11T08:54:15.000Z" } ``` --- ## [ZH] 提交生成任务 (Generation) **URL:** `https://app.deckflow.com/docs/zh/api/create.md` # 提交生成任务 (Generation) > 使用复杂文档、文本提示词或网页链接生成专业的演示文稿幻灯片 (PPTX)。 **HTTP Method:** `POST` **Endpoint:** `/tools/tasks` ## 接口规格说明 创建一个异步的幻灯片生成任务。表单参数中 `type` 值必须固定为 `generation`。 POST `/tools/tasks` 调试接口 ### 请求头 | 请求头 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `Authorization` | `String` | 是 | `Bearer ` — 您的开发者 API 密钥。 | | `Content-Type` | `String` | 是 | 必须为 `multipart/form-data`。 | ### POST 请求体参数 (Form Data) | 参数名 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `spaceId` | `String` | 否 | 目标工作空间 Space ID。 | | `files` | `File` | 否 | 参考的源文档文件（支持 PDF、Word 或 Markdown），支持上传多个文件。 | | `type` | `String` | 是 | 任务类型。固定值：`generation`。 | | `name` | `String` | 否 | 任务显示名称，例如 `"AI 生成文档任务"`。 | | `params` | `String (JSON)` | 是 | 包含任务参数的 JSON 字符串。详细字段如下。 | ## 任务参数说明 (params) 在 `params` JSON 字符串内部支持的参数字段： | 字段 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `inputText` | `String` | 否 | 用于构建幻灯片结构的主题描述、网页链接 URL 或原始文本。 | | `enableSearch` | `Boolean` | 否 | 是否启用网页搜索以研究并丰富内容细节。默认值：`false`。 | | `advancedModel` | `Boolean` | 否 | 是否使用深度推理 AI 模型，以获得更好的逻辑排版和更具创意的幻灯片。默认值：`false`。 | | `fastMode` | `Boolean` | 否 | 是否开启快速模式，优先输出排版速度而非极致的细节优化。默认值：`false`。 | | `intent` | `String` | 否 | 自定义目标意图或指示。 | | `audience` | `String` | 否 | 目标受众特征，用于指导 AI 选择幻灯片布局和文案风格。 | | `pageCount` | `Integer` | 否 | 需要生成的幻灯片页数/目标页数。 | | `author` | `String` | 否 | 生成 PPTX 文件元数据中的作者署名。 | | `notifyURL` | `String` | 否 | 任务状态变更通知的回调 Webhook 地址。 | ### Request Examples #### cURL Request Example ```bash curl --location 'https://app.deckflow.com/api/tools/tasks' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'spaceId="space-default"' \ --form 'files=@"/path/to/presentation.pptx"' \ --form 'type="generation"' \ --form 'name="AI 生成文档任务"' \ --form 'params="{\"inputText\":\"编写一份关于可再生能源行业发展趋势的分析报告，重点突出太阳能和风能的市场占比。\",\"enableSearch\":true,\"advancedModel\":false,\"fastMode\":false,\"pageCount\":10}"' ``` #### JavaScript Request Example ```javascript const formData = new FormData(); formData.append('spaceId', 'space-default'); formData.append('files', fileInput.files[0]); // presentation.pptx formData.append('type', 'generation'); formData.append('name', 'AI 生成文档任务'); formData.append('params', '{"inputText":"编写一份关于可再生能源行业发展趋势的分析报告，重点突出太阳能和风能的市场占比。","enableSearch":true,"advancedModel":false,"fastMode":false,"pageCount":10}'); fetch('https://app.deckflow.com/api/tools/tasks', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' }, body: formData }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python 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/octet-stream")) ] data = { "spaceId": "space-default", "type": "generation", "name": "AI 生成文档任务", "params": '{"inputText":"编写一份关于可再生能源行业发展趋势的分析报告，重点突出太阳能和风能的市场占比。","enableSearch":true,"advancedModel":false,"fastMode":false,"pageCount":10}' } response = requests.post(url, headers=headers, files=files, data=data) print(response.json()) ``` ### Response Examples #### Response 200 ```json {{ "id": "task-uuid-string", "spaceId": "space-default", "name": "AI 生成文档任务", "type": "generation", "status": "pending", "preview": null, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:00.000Z" }} ``` #### Response 400 ```json {{ "error": {{ "code": "invalid_parameter", "message": "type and params are required parameters." }} }} ``` #### Response 401 ```json {{ "error": {{ "code": "unauthorized", "message": "Invalid API Key or authorization header." }} }} ``` --- ## [ZH] get-generation-result **URL:** `https://app.deckflow.com/docs/zh/api/get-generation-result.md` --- ## [ZH] 查询生成任务 **URL:** `https://app.deckflow.com/docs/zh/api/get-generation-task.md` # 查询生成任务 > 查询演示文稿生成任务的执行进度及最终下载链接。 **HTTP Method:** `GET` **Endpoint:** `/tools/tasks/:id` ## 接口规格说明 查询生成任务的执行进度，并在任务完成后从 `result.url` 中获取最终下载详情。 GET `/tools/tasks/:id` 调试接口 ### 请求头 | 请求头 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `Authorization` | `String` | 是 | `Bearer ` — 您的开发者 API 密钥。 | ### 路径参数 | 参数名 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `id` | `String` | 是 | 提交生成任务时返回的任务 taskId。 | ### Request Examples #### cURL Request Example ```bash curl -X GET "https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC" \ -H "Authorization: Bearer YOUR_API_KEY" ``` #### JavaScript Request Example ```javascript fetch('https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python import requests url = "https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC" headers = { "Authorization": "Bearer YOUR_API_KEY" } response = requests.get(url, headers=headers) print(response.json()) ``` ### Response Examples #### Response 200 ```json {{ "id": "Pt1AtI67yauC", "spaceId": "space-default", "type": "generation", "status": "success", "error": null, "progress": 100, "params": {{ "inputText": "编写一份关于可再生能源行业发展趋势的分析报告，重点突出太阳能和风能的市场占比。", "enableSearch": true, "pageCount": 10 }}, "result": {{ "url": "https://app.deckflow.com/api/tasks/Pt1AtI67yauC/download", "format": "pptx", "sizeBytes": 2048576 }}, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:15.000Z" }} ``` #### Response 400 ```json {{ "error": {{ "code": "invalid_parameter", "message": "The request parameters are invalid or missing." }} }} ``` #### Response 401 ```json {{ "error": {{ "code": "unauthorized", "message": "Invalid API Key or authorization header." }} }} ``` #### Response 429 ```json {{ "error": {{ "code": "rate_limit_exceeded", "message": "Too many requests. Please slow down and try again later." }} }} ``` --- ## [ZH] 查询焕新任务 **URL:** `https://app.deckflow.com/docs/zh/api/get-revamp-task.md` # 查询焕新任务 > 查询演示文稿焕新任务的执行进度及最终下载链接。 **HTTP Method:** `GET` **Endpoint:** `/tools/tasks/:id` ## 接口规格说明 查询焕新任务的执行进度，并在任务完成后从 `result.url` 中获取最终下载详情。 GET `/tools/tasks/:id` 调试接口 ### 请求头 | 请求头 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `Authorization` | `String` | 是 | `Bearer ` — 您的开发者 API 密钥。 | ### 路径参数 | 参数名 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `id` | `String` | 是 | 提交焕新任务时返回的任务 taskId。 | ### Request Examples #### cURL Request Example ```bash curl -X GET "https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC" \ -H "Authorization: Bearer YOUR_API_KEY" ``` #### JavaScript Request Example ```javascript fetch('https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python import requests url = "https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC" headers = { "Authorization": "Bearer YOUR_API_KEY" } response = requests.get(url, headers=headers) print(response.json()) ``` ### Response Examples #### Response 200 ```json {{ "id": "Pt1AtI67yauC", "spaceId": "space-default", "type": "revamp", "status": "success", "error": null, "progress": 100, "params": {{ "inputText": "将字体更改为 Outfit 并使用绿蓝配色组合" }}, "result": {{ "url": "https://app.deckflow.com/api/tasks/Pt1AtI67yauC/download", "format": "pptx", "sizeBytes": 2205120 }}, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:25.000Z" }} ``` #### Response 400 ```json {{ "error": {{ "code": "invalid_parameter", "message": "The request parameters are invalid or missing." }} }} ``` #### Response 401 ```json {{ "error": {{ "code": "unauthorized", "message": "Invalid API Key or authorization header." }} }} ``` #### Response 429 ```json {{ "error": {{ "code": "rate_limit_exceeded", "message": "Too many requests. Please slow down and try again later." }} }} ``` --- ## [ZH] get-translation-result **URL:** `https://app.deckflow.com/docs/zh/api/get-translation-result.md` --- ## [ZH] 查询翻译任务 **URL:** `https://app.deckflow.com/docs/zh/api/get-translation-task.md` # 查询翻译任务 > 查询演示文稿翻译任务的执行进度及最终下载链接。 **HTTP Method:** `GET` **Endpoint:** `/tools/tasks/:id` ## 接口规格说明 查询翻译任务的执行进度，并在任务完成后从 `result.url` 中获取最终下载详情。 GET `/tools/tasks/:id` 调试接口 ### 请求头 | 请求头 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `Authorization` | `String` | 是 | `Bearer ` — 您的开发者 API 密钥。 | ### 路径参数 | 参数名 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `id` | `String` | 是 | 提交翻译任务时返回的任务 taskId。 | ### Request Examples #### cURL Request Example ```bash curl -X GET "https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC" \ -H "Authorization: Bearer YOUR_API_KEY" ``` #### JavaScript Request Example ```javascript fetch('https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python import requests url = "https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC" headers = { "Authorization": "Bearer YOUR_API_KEY" } response = requests.get(url, headers=headers) print(response.json()) ``` ### Response Examples #### Response 200 ```json {{ "id": "Pt1AtI67yauC", "spaceId": "space-default", "type": "translation", "status": "success", "error": null, "progress": 100, "params": {{ "from": "zh", "to": "en" }}, "result": {{ "url": "https://app.deckflow.com/api/tasks/Pt1AtI67yauC/download", "format": "pptx", "sizeBytes": 1845120 }}, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:20.000Z" }} ``` #### Response 400 ```json {{ "error": {{ "code": "invalid_parameter", "message": "The request parameters are invalid or missing." }} }} ``` #### Response 401 ```json {{ "error": {{ "code": "unauthorized", "message": "Invalid API Key or authorization header." }} }} ``` #### Response 429 ```json {{ "error": {{ "code": "rate_limit_exceeded", "message": "Too many requests. Please slow down and try again later." }} }} ``` --- ## [ZH] 提交焕新任务 (Revamp) **URL:** `https://app.deckflow.com/docs/zh/api/revamp.md` # 提交焕新任务 (Revamp) > 升级演示文稿排版、配色以及品牌 DNA，同时保留幻灯片的原始文本内容。 **HTTP Method:** `POST` **Endpoint:** `/tools/tasks` ## 接口规格说明 创建一个异步的幻灯片焕新任务。表单参数中 `type` 值必须固定为 `revamp`。 POST `/tools/tasks` 调试接口 ### 请求头 | 请求头 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `Authorization` | `String` | 是 | `Bearer ` — 您的开发者 API 密钥。 | | `Content-Type` | `String` | 是 | 必须为 `multipart/form-data`。 | ### POST 请求体参数 (Form Data) | 参数名 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `spaceId` | `String` | 否 | 目标工作空间 Space ID。 | | `files` | `File` | 是 | 待焕新的演示文稿文件（支持 PPTX 格式），支持上传多个文件。 | | `type` | `String` | 是 | 任务类型。固定值：`revamp`。 | | `name` | `String` | 否 | 任务显示名称，例如 `"AI 焕新文档任务"`。 | | `params` | `String (JSON)` | 是 | 包含焕新参数的 JSON 字符串。详细字段如下。 | ## 任务参数说明 (params) 在 `params` JSON 字符串内部支持的参数字段： | 字段 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `inputText` | `String` | 否 | 排版风格指南、配色规则或品牌 DNA 说明，用于指导幻灯片焕新设计。 | | `advancedModel` | `Boolean` | 否 | 是否使用高级设计推理 AI。默认值：`false`。 | | `fastMode` | `Boolean` | 否 | 是否优先开启快速模式。默认值：`false`。 | | `notifyURL` | `String` | 否 | 任务状态变更通知的回调 Webhook 地址。 | ### Request Examples #### cURL Request Example ```bash curl --location 'https://app.deckflow.com/api/tools/tasks' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'spaceId="space-default"' \ --form 'files=@"/path/to/presentation.pptx"' \ --form 'type="revamp"' \ --form 'name="AI 焕新文档任务"' \ --form 'params="{\"inputText\":\"将字体更改为 Outfit 并使用绿蓝配色组合\",\"advancedModel\":false,\"fastMode\":false}"' ``` #### JavaScript Request Example ```javascript const formData = new FormData(); formData.append('spaceId', 'space-default'); formData.append('files', fileInput.files[0]); // presentation.pptx formData.append('type', 'revamp'); formData.append('name', 'AI 焕新文档任务'); formData.append('params', '{"inputText":"将字体更改为 Outfit 并使用绿蓝配色组合","advancedModel":false,"fastMode":false}'); fetch('https://app.deckflow.com/api/tools/tasks', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' }, body: formData }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python 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/octet-stream")) ] data = { "spaceId": "space-default", "type": "revamp", "name": "AI 焕新文档任务", "params": '{"inputText":"将字体更改为 Outfit 并使用绿蓝配色组合","advancedModel":false,"fastMode":false}' } response = requests.post(url, headers=headers, files=files, data=data) print(response.json()) ``` ### Response Examples #### Response 200 ```json {{ "id": "task-uuid-string", "spaceId": "space-default", "name": "AI 焕新文档任务", "type": "revamp", "status": "pending", "preview": null, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:00.000Z" }} ``` #### Response 400 ```json {{ "error": {{ "code": "invalid_parameter", "message": "type and params are required parameters." }} }} ``` #### Response 401 ```json {{ "error": {{ "code": "unauthorized", "message": "Invalid API Key or authorization header." }} }} ``` --- ## [ZH] 文件转换器 **URL:** `https://app.deckflow.com/docs/zh/api/tools-converter.md` # 文件转换器 > 文件转换器 (File Converter) 后端接口及具体任务参数规范，支持 HTML、Image、Keynote、Markdown、PDF、PPT/PPTX, Word 等格式之间的转换。 **HTTP Method:** `POST` **Endpoint:** `/tools/tasks` ## API 接口 文件转换任务是异步处理的。使用以下两个接口来创建和查询任务。点击右侧的“调试接口”打开交互式控制台。 POST `/tools/tasks` 调试接口 创建一个异步转换任务。表单参数中 `type` 值对应相应的工具 ID。 GET `/tools/tasks/:id` 调试接口 查询转换任务的执行状态，并在此任务完成后通过 `result.url` 获取最终输出的下载链接。 ### 请求头 | 请求头 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `Authorization` | `String` | 是 | `Bearer ` — 您的开发者 API 密钥。 | | `Content-Type` | `String` | 是 (POST) | 必须为 `multipart/form-data`。 | ### POST 请求体参数 (Form Data) | 参数名 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `files` | `File` | 是 | 要处理的源文件。支持上传多个文件。 | | `type` | `String` | 是 | 任务类型标识符。例如：`convertor.ppt2pdf`。 | | `params` | `String (JSON)` | 否 | 工具特定参数的 JSON 字符串。默认为空 JSON 字符串 `"{}"`。 | | `notifyURL` | `String` | 否 | Webhook 回调 URL，用于接收任务状态更新通知。 | ## 任务参数说明 文件转换器分类下的具体任务类型标识、格式与大小限制、以及特定请求参数 (`params`) 如下： | 工具名称 (UI 展示) | Tool ID | Backend Task 类型 (`type`) | 接受的格式扩展名 (`accept`) | 单个文件大小上限 | Special 参数名s (`params`) | | --- | --- | --- | --- | --- | --- | | **HTML to PNG** | `html2png` | `convertor.html2png` | `.html`, `.htm` | 50 MB | `{}` *支持直接粘贴 HTML 代码作为文件输入* | | **HTML to PPTX** | `html2pptx` | `convertor.html2pptx` | `.html`, `.htm` | 50 MB | `{"needEmbedFonts": boolean}` *是否在生成的 PPTX 中嵌入字体。支持粘贴 HTML* | | **Image to WebP** | `image-convert-webp` | `image.convertWebp` | `image/*` | 100 MB | `{}` | | **Keynote to HTML** | `keynote2html` | `convertor.keynote2html` | `.key` | 300 MB | `{}` | | **Keynote to Image** | `keynote2image` | `convertor.keynote2image` | `.key` | 300 MB | `{}` | | **Keynote to PDF** | `keynote2pdf` | `convertor.keynote2pdf` | `.key` | 300 MB | `{}` | | **Markdown to Image** | `markdown2png` | `convertor.markdown2png` | `.md`, `.markdown` | 10 MB | `{}` *支持直接粘贴 Markdown 文本作为文件输入* | | **PDF to Image** | `pdf2image` | `convertor.pdf2image` | `.pdf` | 300 MB | `{}` | | **PPT to PPTX** | `ppt2pptx` | `convertor.ppt2pptx` | `.ppt` | 300 MB | `{}` | | **PowerPoint to PDF** | `ppt2pdf` | `convertor.ppt2pdf` | `.ppt`, `.pptx` | 300 MB | `{}` | | **PowerPoint to Image** | `ppt2image` | `convertor.ppt2image` | `.ppt`, `.pptx` | 300 MB | `{}` | | **PowerPoint to Video** | `ppt2video` | `convertor.ppt2video` | `.ppt`, `.pptx` | 300 MB | `{}` | | **Word to PDF** | `doc2pdf` | `convertor.doc2pdf` | `.doc`, `.docx` | 300 MB | `{}` | ### Request Examples #### cURL Request Example ```bash curl --location 'https://app.deckflow.com/api/tools/tasks' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'files=@"presentation.pptx"' \ --form 'type="convertor.ppt2pdf"' \ --form 'params="{}"' ``` #### JavaScript Request Example ```javascript const formData = new FormData(); formData.append('files', fileInput.files[0]); formData.append('type', 'convertor.ppt2pdf'); formData.append('params', '{}'); fetch('https://app.deckflow.com/api/tools/tasks', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' }, body: formData }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python 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/octet-stream")) ] data = { "type": "convertor.ppt2pdf", "params": "{}" } response = requests.post(url, headers=headers, files=files, data=data) print(response.json()) ``` ### Response Examples #### Response 200 ```json { "id": "task-uuid-string", "spaceId": "space-default", "name": "presentation.pptx", "type": "convertor.ppt2pdf", "status": "pending", "preview": null, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:00.000Z" } ``` #### Response 400 ```json { "error": { "code": "invalid_parameter", "message": "files and type are required parameters." } } ``` #### Response 401 ```json { "error": { "code": "unauthorized", "message": "无效的 API Key 或授权头。" } } ``` --- ## [ZH] 提取器 **URL:** `https://app.deckflow.com/docs/zh/api/tools-extractor.md` # 提取器 > 提取器 API 规格和任务参数，支持图片 OCR 文本识别、PPTX 字体检测和文本提取。 **HTTP Method:** `POST` **Endpoint:** `/tools/tasks` ## API 接口 文件提取任务为异步处理。使用以下两个接口进行任务创建与结果获取。点击右侧的“调试接口”可打开交互式控制台。 POST `/tools/tasks` 调试接口 创建一个异步提取任务。表单参数中 `type` 值对应相应的工具 ID。 GET `/tools/tasks/:id` 调试接口 查询提取任务的执行状态，并在完成后通过 `result.url` 获取最终输出的下载链接。 ### 请求头 | 请求头 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `Authorization` | `String` | 是 | `Bearer ` — 您的开发者 API 密钥。 | | `Content-Type` | `String` | 是 (POST) | 必须为 `multipart/form-data`。 | ### POST 请求体参数 (Form Data) | 参数名 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `files` | `File` | 是 | 待处理的源文件。支持上传多个文件。 | | `type` | `String` | 是 | 任务类型标识符。例如：`image.ocr`。 | | `params` | `String (JSON)` | 否 | 包含工具特定参数的 JSON 字符串。默认为空 JSON 字符串 `"{}"`。 | | `notifyURL` | `String` | 否 | Webhook 回调 URL，用于接收任务状态更新通知。 | ## 任务参数说明 ### Image OCR (图片文本识别) 提取图片中的多语言文本信息。支持 `image/*` 格式，文件上限 50 MB。`params` 参数结构如下： ```json { "language": "zh-hans" // string。识别语言。可选值: "zh-hans" (简体中文) | "zh-hant" (繁体中文) | "en" (英文) | "ja" (日文) | "ko" (韩文) | "fr" (法文) | "de" (德文) | "es" (西班牙文) } ``` ### PPTX Font Finder (PPTX 字体查找器) 扫描并列出幻灯片中引用的所有字体列表。支持 `.pptx` 格式，文件上限 300 MB，`params` 参数结构为 `{}`。 ### PPTX Text Extractor (PPTX 文本提取器) 提取幻灯片内所有图层的文本元素，支持多维度的结构化过滤。支持 `.pptx` 格式，文件上限 300 MB。`params` 参数结构如下： ```json { "hasChildren": false, // boolean。是否包含子图层（递归提取子级形状文字） "pickPages": [1, 2, 5], // array。可选。指定提取的幻灯片页码列表（从 1 开始计数） "imageFilter": 0.2, // number (范围 0~1)。可选。根据图像面积比例过滤元素 "includeLayout": false, // boolean。是否提取版式页面（Layout）中的文字 "includeMaster": false, // boolean。是否提取母版页面（Master）中的文字 "includeNotes": false, // boolean。是否提取备注（Notes）中的文字 "ignoreEmptyText": true, // boolean。是否过滤掉空白文本框 "onlyBrief": true // boolean。是否过滤空段落并返回简要结构以减小体积 } ``` ### Request Examples #### cURL Request Example ```bash curl --location 'https://app.deckflow.com/api/tools/tasks' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'files=@"presentation.png"' \ --form 'type="image.ocr"' \ --form 'params="{\"language\":\"zh-hans\"}"' ``` #### JavaScript Request Example ```javascript const formData = new FormData(); formData.append('files', fileInput.files[0]); formData.append('type', 'image.ocr'); formData.append('params', '{"language":"zh-hans"}'); fetch('https://app.deckflow.com/api/tools/tasks', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' }, body: formData }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python import requests url = "https://app.deckflow.com/api/tools/tasks" headers = { "Authorization": "Bearer YOUR_API_KEY" } files = [ ("files", ("presentation.png", open("presentation.png", "rb"), "image/png")) ] data = { "type": "image.ocr", "params": '{"language":"zh-hans"}' } response = requests.post(url, headers=headers, files=files, data=data) print(response.json()) ``` ### Response Examples #### Response 200 ```json { "id": "task-uuid-string", "spaceId": "space-default", "name": "image.png", "type": "image.ocr", "status": "pending", "preview": null, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:00.000Z" } ``` #### Response 400 ```json { "error": { "code": "invalid_parameter", "message": "files and type are required parameters." } } ``` #### Response 401 ```json { "error": { "code": "unauthorized", "message": "无效的 API Key 或授权头。" } } ``` --- ## [ZH] 合并与拆分器 **URL:** `https://app.deckflow.com/docs/zh/api/tools-merger-splitter.md` # 合并与拆分器 > 合并与拆分器 API 规格和任务参数，支持合并多个 PPTX 文件、将 HTML 页面打包为独立播放器、或拆分 PPTX 演示文稿。 **HTTP Method:** `POST` **Endpoint:** `/tools/tasks` ## API 接口 合并与拆分任务为异步处理。使用以下两个接口进行任务创建与结果获取。点击右侧的“调试接口”可打开交互式控制台。 POST `/tools/tasks` 调试接口 创建一个异步的合并或拆分任务。表单参数中 `type` 值对应相应的工具 ID。 GET `/tools/tasks/:id` 调试接口 查询合并/拆分任务的执行状态，并在完成后通过 `result.url` 获取最终输出的下载链接。 ### 请求头 | 请求头 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `Authorization` | `String` | 是 | `Bearer ` — 您的开发者 API 密钥。 | | `Content-Type` | `String` | 是 (POST) | 必须为 `multipart/form-data`。 | ### POST 请求体参数 (Form Data) | 参数名 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `files` | `File` | 是 | 待处理的源文件。支持上传多个文件。`pptx.join` 需要至少 2 个文件。 | | `type` | `String` | 是 | 任务类型标识符。例如：`pptx.join`。 | | `params` | `String (JSON)` | 否 | 包含工具特定参数的 JSON 字符串。默认为空 JSON 字符串 `"{}"`。 | | `notifyURL` | `String` | 否 | Webhook 回调 URL，用于接收任务状态更新通知。 | ## 任务参数说明 ### PPTX Merger (PPTX 合并) 按顺序将多个 PPTX 文件合并为一个演示文稿。支持 `.pptx` 格式，每个文件大小限制为 300 MB。文件上传的顺序决定了合并幻灯片的顺序。`params` 为空对象 `{}`。 ### HTML Player Pack (网页播放器打包) 将多个独立的 HTML 幻灯片打包为一个统一的、美观的网页播放器环境，并带有内置的导航控制。支持 `.html` and `.htm` 格式，每个文件大小限制为 50 MB。`params` 的结构如下： ```json { "contents": [{}, {}], // array of objects。是否必填。长度和顺序必须与上传文件的顺序相匹配 "pageWidth": 1280, // number。播放器画布宽度分辨率（像素） "pageHeight": 720, // number。播放器画布高度分辨率（像素） "title": "Presentation", // string。播放器中显示的主演示文稿标题 "description": "Details", // string。播放器中显示的副标题或简短描述 "brandMarkPosition": "none" // string。品牌 Logo 的位置，默认为 "none" } ``` ### PPTX Splitter (PPTX 拆分) 将多页 PPTX 文件拆分为独立的单页 PPTX 演示文稿。支持 `.pptx` 格式，文件大小限制为 300 MB。`params` 为空对象 `{}`（完成后，输出将是一个包含所有拆分后单页 PPTX 文件的 ZIP 压缩包）。 ### Request Examples #### cURL Request Example ```bash curl --location 'https://app.deckflow.com/api/tools/tasks' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'files=@"presentation1.pptx"' \ --form 'files=@"presentation2.pptx"' \ --form 'type="pptx.join"' \ --form 'params="{}"' ``` #### JavaScript Request Example ```javascript const formData = new FormData(); // Add all files to the form formData.append('files', fileInput.files[0]); // presentation1.pptx formData.append('files', fileInput.files[1]); // presentation2.pptx formData.append('type', 'pptx.join'); formData.append('params', '{}'); fetch('https://app.deckflow.com/api/tools/tasks', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' }, body: formData }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python import requests url = "https://app.deckflow.com/api/tools/tasks" headers = { "Authorization": "Bearer YOUR_API_KEY" } files = [ ("files", ("presentation1.pptx", open("presentation1.pptx", "rb"), "application/octet-stream")), ("files", ("presentation2.pptx", open("presentation2.pptx", "rb"), "application/octet-stream")) ] data = { "type": "pptx.join", "params": "{}" } response = requests.post(url, headers=headers, files=files, data=data) print(response.json()) ``` ### Response Examples #### Response 200 ```json { "id": "task-uuid-string", "spaceId": "space-default", "name": "joined-presentation.pptx", "type": "pptx.join", "status": "pending", "preview": null, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:00.000Z" } ``` #### Response 400 ```json { "error": { "code": "invalid_parameter", "message": "files and type are required parameters." } } ``` #### Response 401 ```json { "error": { "code": "unauthorized", "message": "无效的 API Key 或授权头。" } } ``` --- ## [ZH] 优化器 **URL:** `https://app.deckflow.com/docs/zh/api/tools-optimizer.md` # 优化器 > 优化器 API 规格和任务参数，支持文件压缩、图像尺寸修改、PPTX 字体嵌入以及视频大小压缩。 **HTTP Method:** `POST` **Endpoint:** `/tools/tasks` ## API 接口 优化任务是异步处理的。使用以下两个接口来创建和查询任务。点击右侧的“调试接口”打开交互式控制台。 POST `/tools/tasks` 调试接口 创建一个异步的优化任务。表单参数中 `type` 值对应相应的工具 ID。 GET `/tools/tasks/:id` 调试接口 查询优化任务的执行状态，并在此任务完成后通过 `result.url` 获取最终输出的下载链接。 ### 请求头 | 请求头 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `Authorization` | `String` | 是 | `Bearer ` — 您的开发者 API 密钥。 | | `Content-Type` | `String` | 是 (POST) | 必须为 `multipart/form-data`。 | ### POST 请求体参数 (Form Data) | 参数名 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `files` | `File` | 是 | 待处理的源文件。支持上传多个文件。 | | `type` | `String` | 是 | 任务类型标识符。例如：`file.compress`。 | | `params` | `String (JSON)` | 否 | 包含工具特定参数的 JSON 字符串。默认为空 JSON 字符串 `"{}"`。 | | `notifyURL` | `String` | 否 | Webhook 回调 URL，用于接收任务状态更新通知。 | ## 任务参数说明 ### File Compressor (文件压缩器) 减小办公文档和压缩包的文件大小，同时最大化视觉质量。支持 `.zip`、`.pptx`、`.key`、`.docx`、`.xlsx` 格式，文件大小限制为 300 MB。`params` 为空对象 `{}`。 ### Image Resizer (图片尺寸修改) 在保持原始宽高比的同时自定义调整图像大小。支持 `image/*` 格式，文件大小限制为 100 MB。`params` 结构如下： ```json { "maxWidth": 800, // number。可选。以像素限制最大宽度（与 maxHeight 互斥） "maxHeight": 600 // number。可选。以像素限制最大高度（与 maxWidth 互斥） } ``` ### PPTX Font Embedder (PPTX 字体嵌入器) 将外部字体直接嵌入到 PPTX 演示文稿中，以解决因缺少系统字体而导致的格式差异。支持 `.pptx` 格式，文件大小限制为 300 MB。`params` 结构如下： ```json { "usedFonts": ["Inter", "Roboto"] // array of strings。从 Google Fonts 字体库中需要嵌入的字体家族名称数组 } ``` ### Video Size Reducer (视频压缩器) 高效压缩视频文件大小以减少带宽占用。支持 `video/*`（如 MP4、MOV 等常用格式），文件大小限制为 300 MB。`params` 为空对象 `{}`。 ### Request Examples #### cURL Request Example ```bash curl --location 'https://app.deckflow.com/api/tools/tasks' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'files=@"archive.zip"' \ --form 'type="file.compress"' \ --form 'params="{}"' ``` #### JavaScript Request Example ```javascript const formData = new FormData(); formData.append('files', fileInput.files[0]); formData.append('type', 'file.compress'); formData.append('params', '{}'); fetch('https://app.deckflow.com/api/tools/tasks', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' }, body: formData }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python import requests url = "https://app.deckflow.com/api/tools/tasks" headers = { "Authorization": "Bearer YOUR_API_KEY" } files = [ ("files", ("archive.zip", open("archive.zip", "rb"), "application/zip")) ] data = { "type": "file.compress", "params": "{}" } response = requests.post(url, headers=headers, files=files, data=data) print(response.json()) ``` ### Response Examples #### Response 200 ```json { "id": "task-uuid-string", "spaceId": "space-default", "name": "archive.zip", "type": "file.compress", "status": "pending", "preview": null, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:00.000Z" } ``` #### Response 400 ```json { "error": { "code": "invalid_parameter", "message": "files and type are required parameters." } } ``` #### Response 401 ```json { "error": { "code": "unauthorized", "message": "无效的 API Key 或授权头。" } } ``` --- ## [ZH] 提交翻译任务 (Translation) **URL:** `https://app.deckflow.com/docs/zh/api/translate.md` # 提交翻译任务 (Translation) > 在保持排版格式和视觉设计的前提下翻译演示文稿文件（PPTX、PDF 等）。 **HTTP Method:** `POST` **Endpoint:** `/tools/tasks` ## 接口规格说明 创建一个异步的幻灯片翻译任务。表单参数中 `type` 值必须固定为 `translation`。 POST `/tools/tasks` 调试接口 ### 请求头 | 请求头 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `Authorization` | `String` | 是 | `Bearer ` — 您的开发者 API 密钥。 | | `Content-Type` | `String` | 是 | 必须为 `multipart/form-data`。 | ### POST 请求体参数 (Form Data) | 参数名 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `spaceId` | `String` | 否 | 目标工作空间 Space ID。 | | `files` | `File` | 是 | 需要翻译的演示文稿文件（PPTX、Keynote、PDF、Word、Excel）。支持上传多个文件。 | | `type` | `String` | 是 | 任务类型。固定值：`translation`。 | | `name` | `String` | 否 | 任务显示名称，例如 `"AI 翻译文档任务"`。 | | `params` | `String (JSON)` | 是 | 包含翻译参数的 JSON 字符串。详细字段说明见下方。 | ## 任务参数说明 (params) 在 `params` JSON 字符串内部支持的参数字段： | 字段 | 类型 | 是否必填 | 描述 | | --- | --- | --- | --- | | `from` | `String` | 是 | 源语言代码，例如 `"zh"`。 | | `to` | `String` | 是 | 目标语言代码，例如 `"en"`。 | | `notifyURL` | `String` | 否 | 任务状态变更通知的回调 Webhook 地址。 | ## 支持的语言列表 翻译 API 在 `from`（源语言）和 `to`（目标语言）字段中支持以下语言代码： 🔥 ### 常用语言 / Popular | 语言代码 | 对应语言 | | --- | --- | | `en` | 英语 (English) | | `zh-CN` | 简体中文 (Simplified Chinese) | | `zh-TW` | 繁体中文 (Traditional Chinese) | | `ja` | 日语 (Japanese) | | `ko` | 韩语 (Korean) | | `es` | 西班牙语 (Spanish) | 🇪🇺 ### 欧洲地区 / Europe | 语言代码 | 对应语言 | | --- | --- | | `fr` | 法语 (French) | | `de` | 德语 (German) | | `it` | 意大利语 (Italian) | | `nl` | 荷兰语 (Dutch) | | `ru` | 俄语 (Russian) | | `pl` | 波兰语 (Polish) | | `sv` | 瑞典语 (Swedish) | | `da` | 丹麦语 (Danish) | | `fi` | 芬兰语 (Finnish) | | `el` | 希腊语 (Greek) | | `cs` | 捷克语 (Czech) | | `ro` | 罗马尼亚语 (Romanian) | | `hu` | 匈牙利语 (Hungarian) | | `uk` | 乌克兰语 (Ukrainian) | 🌏 ### 亚洲地区 / Asia | 语言代码 | 对应语言 | | --- | --- | | `ar` | 阿拉伯语 (Arabic) | | `th` | 泰语 (Thai) | | `vi` | 越南语 (Vietnamese) | | `he` | 希伯来语 (Hebrew) | 🌎 ### 美洲及其他 / Americas & Others | 语言代码 | 对应语言 | | --- | --- | | `pt-BR` | 巴西葡萄牙语 (Brazilian Portuguese) | | `tr` | 土耳其语 (Turkish) | ### Request Examples #### cURL Request Example ```bash curl --location 'https://app.deckflow.com/api/tools/tasks' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'spaceId="space-default"' \ --form 'files=@"/path/to/presentation.pptx"' \ --form 'type="translation"' \ --form 'name="AI 翻译文档任务"' \ --form 'params="{\"from\":\"zh\",\"to\":\"en\"}"' ``` #### JavaScript Request Example ```javascript const formData = new FormData(); formData.append('spaceId', 'space-default'); formData.append('files', fileInput.files[0]); // presentation.pptx formData.append('type', 'translation'); formData.append('name', 'AI 翻译文档任务'); formData.append('params', '{"from":"zh","to":"en"}'); fetch('https://app.deckflow.com/api/tools/tasks', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' }, body: formData }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python 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/octet-stream")) ] data = { "spaceId": "space-default", "type": "translation", "name": "AI 翻译文档任务", "params": '{"from":"zh","to":"en"}' } response = requests.post(url, headers=headers, files=files, data=data) print(response.json()) ``` ### Response Examples #### Response 200 ```json {{ "id": "task-uuid-string", "spaceId": "space-default", "name": "AI 翻译文档任务", "type": "translation", "status": "pending", "preview": null, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:00.000Z" }} ``` #### Response 400 ```json {{ "error": {{ "code": "invalid_parameter", "message": "type and params are required parameters." }} }} ``` #### Response 401 ```json {{ "error": {{ "code": "unauthorized", "message": "Invalid API Key or authorization header." }} }} ``` --- ## [ZH] CLI 命令 **URL:** `https://app.deckflow.com/docs/zh/cli/commands.md` # CLI 命令 > deckuse 命令作用于本地 PPTX 工作区。deckops 命令作用于 DeckFlow 云端任务。 ## DeckUse 命令 `deckuse` 命令模式： ```bash deckuse [options] ``` | 命令 | 用途 | | --- | --- | | `deckuse init [--dir ]` | 将 PPTX 解包至本地 DeckUse 工作区。 | | `deckuse status ` | 显示工作区状态。 | | `deckuse commit [-o ]` | 将工作区重新构建为 PPTX。 | | `deckuse list slides ` | 列出幻灯片及推断出的结构。 | | `deckuse show slide ` | 显示单个幻灯片的详细信息。 | | `deckuse get text ` | 从选择器中读取文本。 | | `deckuse set text [-o ]` | 替换选择器处的文本。 | | `deckuse set font-size [-o ]` | 设置字体大小（单位：磅）。 | | `deckuse move --left --top [-o ]` | 按左/上百分比移动匹配的形状。 | | `deckuse replace [--slide ] [--regex] [-o ]` | 全局或在单个幻灯片上替换文本。 | `deckuse` 选择器用于定位幻灯片和形状结构： ```bash deckuse get text ./company.deck "slide:3/title" deckuse get text ./company.deck "slide:1/shape[id=6]/shape[id=9]" deckuse get text ./company.deck "slide:1/#6,9" deckuse set text ./company.deck "shape[type=textbox]" "Updated" ``` 写入行为说明： - 当 `` 是工作区目录时，写入命令会直接修改工作区；`-o/--output` 是可选的，如果提供则会导出 PPTX 文件。 - 当 `` 是 `.pptx` 文件路径时，写入命令必须使用 `-o/--output`，因为 CLI 需要指定一个明确的输出文件。 - `deckuse` 不进行幻灯片渲染。渲染和格式转换请使用 `deckops`。 ## DeckOps 命令 `deckops` 命令模式： ```bash deckops [--json] [options] ``` 在脚本和智能体中，请使用 `--json` 参数以获取机器可读的输出。 ### 登录与配置 ```bash deckops login [--port ] deckops config set-token deckops config set-space deckops config set-api-base deckops config show ``` 默认的回调端口为 `3737`。配置存储在 `~/.deckops/config.json` 路径。 ### 任务管理 ```bash deckops task list [--type ] [--limit ] [--offset ] deckops task get deckops task delete ``` ### 压缩 ```bash deckops compress [--no-wait] [--timeout ] ``` 支持的输入格式包括 `.zip`, `.pptx`, `.key`, `.docx`, `.xlsx`, `.mp4`, `.avi`, `.mov` 以及 `.mkv`。 ### OCR ```bash deckops ocr [--language ] [--no-wait] [--timeout ] ``` 支持的输入格式为 `.jpg`, `.jpeg` 以及 `.png`。默认语言为 `zh-hans`；支持的语言包括 `zh-hans`, `zh-hant`, `en`, `ja`, `ko`, `ar`, `de`, `es`, `fr`, `it`, `pt` 和 `ru`。 ### 提取 ```bash deckops extract [--type ] [--no-wait] [--timeout ] ``` 当前文档中记录的提取类型对应于 `pptx.getFontInfo` 和 `pptx.getTextShapes`。 ### 转换 ```bash deckops convert --to \ [--width ] [--height ] \ [--need-embed-fonts [boolean]] \ [--no-wait] [--timeout ] ``` 支持的输出格式为 `image`, `pdf`, `video`, `html`, `png`, `pptx` 和 `webp`。 转换注意事项： - PPT/PPTX/PDF/KEY 可以渲染为图片（取决于源格式）。 - PPT/PPTX/DOC/DOCX/KEY 可以转换为 PDF（取决于源格式）。 - PPT/PPTX 可以转换为视频。 - KEY 可以转换为 HTML。 - HTML/Markdown 可以转换为 PNG。 - PPT/HTML 可以转换为 PPTX。 - JPG/JPEG/PNG 可以转换为 WebP。 - 多输入文件目前仅支持在 HTML 转 PPTX 转换路径下使用。 - `--width`, `--height` 和 `--need-embed-fonts` 与 HTML 转换路径相关。 ### 生成 ```bash deckops create [input-files...] \ [--input-text ] \ [--enable-search [boolean]] \ [--advanced-model [boolean]] \ [--fast-mode [boolean]] \ [--intent ] \ [--audience ] \ [--page-count ] \ [--author ] \ [--no-wait] [--timeout ] ``` 必须提供 `--input-text` 或输入文件中的至少一个。最多允许两个参考文件。支持的参考文件扩展名为 `.html`, `.pdf`, `.docx`, `.pptx`, `.txt`, `.md`, `.mm`, `.xmind` 和 `.ipynb`。 ### 翻译 ```bash deckops translate \ --from \ --to \ --model \ [--use-glossary [boolean]] \ [--image-translate [boolean]] \ [--no-wait] [--timeout ] ``` 支持的输入格式为 `.docx`, `.pptx`, `.pdf`, `.xlsx` 和 `.key`。源语言支持 `auto` 及常用的语言代码；目标语言需要指定明确支持的语言代码。 ### 合并 ```bash deckops join [--name ] [--no-wait] [--timeout ] ``` 需要至少两个 `.pptx` 文件。文件将按命令行中的指定顺序进行合并。 ### 运行特定的任务类型 ```bash deckops run \ [--param ] \ [--no-wait] [--timeout ] ``` `--param` 参数可以重复指定。在可能的情况下，参数值将被解析为 JSON。 ### REPL ```bash deckops repl ``` 使用 REPL 可以对相同的 `DeckOps` 配置执行重复的交互式操作。 ## 来源依据 - DeckUse GitHub 仓库 README/手册/源码：[https://github.com/deckflow/deckuse](https://github.com/deckflow/deckuse) - DeckOps GitHub 仓库 README/源码：[https://github.com/deckflow/deckops](https://github.com/deckflow/deckops) --- ## [ZH] CLI 示例 **URL:** `https://app.deckflow.com/docs/zh/cli/examples.md` # CLI 示例 > 本地修改 PPTX 结构请使用 DeckUse。如果任务需要云端 DeckFlow 后端处理，请使用 DeckOps。 ## DeckUse: 本地更新 PPTX 文本 ```bash deckuse init company.pptx --dir ./company.deck deckuse list slides ./company.deck deckuse replace ./company.deck "2025" "2026" deckuse commit ./company.deck --output company-2026.pptx ``` 安装后，该工作流完全在本地运行。无需登录、无需 API 密钥、无需后端任务、也无需上传文件。 ## DeckUse: 查看并编辑单张幻灯片 ```bash deckuse init roadmap.pptx --dir ./roadmap.deck deckuse show slide ./roadmap.deck 3 deckuse get text ./roadmap.deck "slide:3/title" deckuse set text ./roadmap.deck "slide:3/title" "2026 Product Roadmap" deckuse set font-size ./roadmap.deck "slide:3/title" 28 deckuse commit ./roadmap.deck --output roadmap-updated.pptx ``` 使用选择器表达式（例如 `slide:3/title`、`shape[type=textbox]` 或 `slide:1/#6,9`）来指定要修改的现有元素。 ## DeckUse: 带显式输出的直接 PPTX 输入 ```bash deckuse replace deck.pptx "OldBrand" "NewBrand" --output deck-brand-updated.pptx deckuse set text deck.pptx "slide:1/title" "New Launch Plan" --output deck-title-updated.pptx ``` 直接编辑原始 `.pptx` 路径（而不是初始化的工作区）时，请传入 `--output` 参数以为修改后的文件指定显式输出路径。 ## DeckOps: 登录和检查任务 ```bash deckops login deckops task list --limit 10 ``` DeckOps 将凭证存储在 `~/.deckops/config.json` 中，并调用 DeckFlow 后端执行任务操作。 ## DeckOps: 生成幻灯片 ```bash deckops create \ --input-text "Please write an API design document for developers" \ --audience "Engineering Team" \ --page-count 6 ``` 当需要基于已有材料生成幻灯片时，请使用参考文件： ```bash deckops create refs.md refs.pdf \ --input-text "Generate a summary based on the reference materials" \ --audience "Management" \ --page-count 8 ``` DeckOps 允许为 `create` 传入最多两个参考文件。 ## DeckOps: 翻译文档 ```bash deckops translate handbook.docx \ --from zh \ --to en \ --model Standard ``` ```bash deckops translate slides.pdf \ --from ja \ --to zh-hans \ --model Pro \ --image-translate true ``` 翻译是一个云端任务，因此该命令需要有效的 DeckOps 令牌/空间以及网络连接。 ## DeckOps: 转换与渲染 ```bash deckops convert slides.pptx --to pdf deckops convert slides.pptx --to video --timeout 900 deckops convert page.html --to pptx --width 1920 --height 1080 --need-embed-fonts true ``` 使用 `--no-wait` 参数让任务在后台启动： ```bash deckops convert slides.pptx --to pdf --no-wait --json deckops task get --json ``` ## DeckOps: 压缩、OCR 和合并 ```bash deckops compress presentation.pptx deckops ocr screenshot.png --language en deckops join cover.pptx chapter-1.pptx appendix.pptx --name combined-deck ``` ## 组合工作流 如果修改是确定性且本地的，请先使用 DeckUse，然后在需要云端操作时使用 DeckOps： ```bash deckuse init source.pptx --dir ./source.deck deckuse replace ./source.deck "2025" "2026" deckuse commit ./source.deck --output source-clean.pptx deckops convert source-clean.pptx --to pdf deckops translate source-clean.pptx --from zh --to en --model Standard ``` 这种拆分能够使简单的结构化编辑保持在本地，同时将云端请求保留给渲染、翻译、OCR、生成和其他后端任务。 ## 来源依据 - DeckUse GitHub: [https://github.com/deckflow/deckuse](https://github.com/deckflow/deckuse) - DeckOps GitHub: [https://github.com/deckflow/deckops](https://github.com/deckflow/deckops) --- ## [ZH] CLI 安装指南 **URL:** `https://app.deckflow.com/docs/zh/cli/install.md` # CLI 安装指南 > 本地编辑 PPTX 结构请安装 DeckUse，使用 DeckFlow 云端任务请安装 DeckOps。这两个包均要求 Node.js 18 或更高版本。 ## DeckUse `DeckUse` 是一款本地优先的命令行工具。它用于在本地文件和本地工作区中对 `PPTX` 进行结构化操作。 ```bash npm install -g deckuse deckuse --help ``` 虽然 GitHub 仓库的 README 中目前显示使用 `npm install -g @deckflow/deckuse` 进行安装，但经 2026-05-27 检查，公开的 npm 注册表中暴露的包名实际为 `deckuse`；当时在公开注册表中无法下载命名空间包 `@deckflow/deckuse`。 若想直接运行 GitHub 仓库源码，可从源码编译安装： ```bash git clone https://github.com/deckflow/deckuse.git cd deckuse pnpm install pnpm build pnpm link --global deckuse --help ``` `DeckUse` 的核心工作流不需要登录、API 密钥、空间 ID 或后端 URL。常规工作流如下： ```bash deckuse init company.pptx --dir ./company.deck deckuse list slides ./company.deck deckuse replace ./company.deck "2025" "2026" deckuse commit ./company.deck --output company-2026.pptx ``` ## DeckOps `DeckOps` 是一款基于云端的任务命令行工具。它将文件上传到 DeckFlow 后端，创建任务，并可选择是否等待任务完成，同时在本地存储身份验证信息。 ```bash npm install -g deckops deckops --help ``` 若想直接运行 GitHub 仓库源码，可从源码编译安装： ```bash git clone https://github.com/deckflow/deckops.git cd deckops npm install npm run build node dist/cli.js --help ``` 使用浏览器登录流程进行身份验证： ```bash deckops login ``` `login` 命令会自动打开浏览器，并默认在 `http://localhost:3737` 接收回调。凭证将存储在： ```text ~/.deckops/config.json ``` 常见的配置文件字段： ```json { "token": "your-auth-token", "spaceId": "your-space-id", "apiBase": "https://app.deckflow.com/v1" } ``` 您也可以手动配置 `DeckOps`： ```bash deckops config set-token deckops config set-space deckops config set-api-base https://app.deckflow.com/v1 deckops config show ``` 大多数 `DeckOps` 命令需要网络连接和有效的凭证。如果凭证缺失，调用 API 的命令会触发登录流程。如果后端返回 `401`，`DeckOps` 将尝试重新登录并重试任务。如果后端返回 `402`，它会在继续执行前打开收银台（付款）流程。 ## 安装选择决策 当您需要进行本地、离线友好的 PPTX 编辑，且不希望将文件发送到云端服务时，只需安装 `deckuse`。 当您需要使用 DeckFlow 后端功能（如生成、翻译、渲染、OCR、压缩、文件转换或长时间运行的任务管理）时，请安装 `deckops`。 很多工作流会同时使用两者：先使用 `DeckUse` 进行本地结构清理，再使用 `DeckOps` 进行云端渲染或翻译。 ## 来源依据 - DeckUse GitHub 仓库：[https://github.com/deckflow/deckuse](https://github.com/deckflow/deckuse) - 2026-05-27 检查的 DeckUse npm 包：[https://www.npmjs.com/package/deckuse](https://www.npmjs.com/package/deckuse) - DeckOps GitHub 仓库：[https://github.com/deckflow/deckops](https://github.com/deckflow/deckops) - 2026-05-27 检查的 DeckOps npm 包：[https://www.npmjs.com/package/deckops](https://www.npmjs.com/package/deckops) --- ## [ZH] Claude Code **URL:** `https://app.deckflow.com/docs/zh/mcp/claude-code.md` # Claude Code > 通过 MCP 将 DeckFlow 连接到 Claude Code，使基于终端的智能体可以直接创建、翻新、翻译、转换、提取、合并、拆分和优化演示文稿文件。 当用户希望在 Claude Code 项目中调用 DeckFlow 时，可以参考本指南。本页面参考了主流连接配置的结构，并使用已确认的 DeckFlow 端点、仅限 API 密钥的身份验证模型、首批支持客户端以及输出临时下载链接的逻辑。相关的 API 密钥传输细节等仍在待确认状态。 ## 前提条件 - 已安装 Claude Code。 - 已安装 Node.js（如果当前 Claude Code MCP 的解析路径有要求）。 - 具备 MCP 访问权限的 DeckFlow 账户。 - 一个 DeckFlow API 密钥。 - 上传或引用 DeckFlow 工作流中所使用源文件的权限。 ## 添加 MCP 服务器 在 Claude Code 交互式会话之外的终端中运行以下命令： ```bash claude mcp add --transport http deckflow https://dev.deckflow.com/mcp/v1/ ``` 要在所有 Claude Code 项目中全局可用，请使用用户作用域参数： ```bash claude mcp add --transport http -s user deckflow https://dev.deckflow.com/mcp/v1/ ``` ## 替代配置：直接编辑配置文件 如果目标 Claude Code 版本支持直接编辑配置文件，请将 DeckFlow 添加至 `~/.claude.json` 中： ```json { "mcpServers": { "deckflow": { "type": "http", "url": "https://dev.deckflow.com/mcp/v1/" } } } ``` 编辑完配置文件后，请重新启动 Claude Code。 ## 身份验证 DeckFlow MCP 仅使用 API 密钥进行身份验证。 最终的文档仍需定义 Claude Code 如何向远程 MCP 服务器安全传输 API 密钥。可能的设计包括客户端机密配置、HTTP 请求头配置或 MCP 身份验证提示。 用户可以在 Claude Code 交互界面中运行以下命令查看 MCP 状态： ```text /mcp ``` 本配置指南目前在等待确认最终的密钥存储方式、API 密钥创建页面 URL 以及环境变量或请求头名称。 ## 验证连接 设置完成后，确认服务器已处于活动状态： ```bash claude mcp list ``` 或者在 Claude Code 内部： ```text /mcp ``` 用户应当能看到 `deckflow` 列在已连接的服务器列表中，并显示 connected 状态和可用的工具。 ## 使用方法 提示词示例如下： ```text 使用 DeckFlow 将此研究 PDF 转换为包含 10 页幻灯片的 PPTX 演示文稿，并在生成的文稿就绪时通知我。 ``` Claude Code 会调用适当的 DeckFlow MCP 工具，轮询任务并返回生成的临时下载链接。 ## 推荐给智能体的指令 为了获得更好的效果，请让 Claude Code 在提交文件任务前先检查 DeckFlow 的功能： ```text 在使用 DeckFlow 之前，调用可用的 capability 或 account 工具，以确认支持的输入格式、输出格式、文件限制，以及 Create、Revamp、Translate 和 Tools 是否可用。 ``` ## 作用域 | 作用域 | 参数 | 配置文件位置 | 可用范围 | | --- | --- | --- | --- | | Local（本地） | 无 | 项目目录下的 `.mcp.json` | 仅限当前项目 | | User（用户） | `-s user` | `~/.claude.json` | 当前用户的所有项目 | ## 待确认的参数 | 参数 | 问题 | | --- | --- | | API 密钥创建 | 用户在何处创建或复制 DeckFlow API 密钥？ | | API 密钥传输 | Claude Code 应通过请求头、机密字段、环境变量还是提示词传递密钥？ | | 凭证存储 | 应该记录什么环境变量和配置文件？ | | 验证工具 | 文档是否应该推荐使用 `get_current_user`、`get_deckflow_capabilities` 还是其他健康检查工具？ | | 输出处理 | 临时下载链接已确认。输出是否也应保存在 DeckFlow 工作区中？ | --- ## [ZH] Claude 网页端 / 桌面端 **URL:** `https://app.deckflow.com/docs/zh/mcp/claude-web.md` # Claude 网页端 / 桌面端 > 通过自定义 MCP 连接器将 DeckFlow 连接到 Claude，使用户可以直接在 Claude 聊天会话中调用演示文稿和文件处理工作流。 本页面参考了主流连接配置的结构，并使用已确认 of DeckFlow 端点、仅限 API 密钥的身份验证模型、首批支持客户端以及输出临时下载链接的逻辑。相关的界面截图、API 密钥传输方式以及套餐要求等细节仍需后续确认。 ## 前提条件 - 支持自定义连接器 (Custom Connector) 的 Claude 套餐计划。 - 具备 MCP 访问权限的 DeckFlow 账户。 - 一个 DeckFlow API 密钥。 - 在 Claude 中上传或引用源文件的权限。 ## 接入配置步骤 ### 1. 注册连接器 在 Claude 中，导航至自定义连接器设置页面： ```text + -> 连接器 (Connector) -> 管理连接器 (Manage Connector) -> + 添加自定义连接器 (+ Add custom connector) ``` 将连接器名称设置为： ```text DeckFlow ``` 将远程 MCP 服务器 URL 设置为： ```text https://dev.deckflow.com/mcp/v1/ ``` ### 2. 身份验证 保存连接器配置后，点击 **连接 (Connect)**。 DeckFlow MCP 仅使用 API 密钥进行身份验证。 Claude 必须支持机密输入流、HTTP 请求头配置或其他经过批准的安全方式，以便向远程 MCP 服务器发送 DeckFlow API 密钥。如果 Claude 自定义连接器无法安全地传输 API 密钥，DeckFlow 可能会开发官方连接器或通过中间密钥交换方案来解决。 ### 3. 配置权限 Claude 可能会在每次调用工具前请求用户许可。为了保证工作流顺畅，用户可以根据 Claude 的权限模型选择“始终允许”该连接器调用 DeckFlow 工具。 最终的文档应该仔细说明，DeckFlow 工具可能会执行文件上传、生成派生文件、读取任务状态，并返回可下载的输出。 ## 使用方法 提示词示例如下： ```text 使用 DeckFlow 将此演示文稿翻译为日语，同时保留版式，然后返回翻译后的文件。 ``` Claude 应当选择匹配的 DeckFlow MCP 工具，提交任务，轮询直到完成，然后返回结果。 ## 建议的首个测试 使用一个低风险的自然语言发现提示词： ```text 使用 DeckFlow MCP 列出此账户可用的支持工作流、输入格式、输出格式以及文件大小限制。 ``` ## 需记录的局限性 | 限制维度 | 待确认的细节 | | --- | --- | | Claude 套餐 | 在发布时，哪些 Claude 套餐支持自定义 MCP 连接器？ | | DeckFlow 套餐 | 哪些 DeckFlow 套餐包含 MCP 访问权限？ | | API 密钥配置 | Claude 用户在何处输入或存储 DeckFlow API 密钥。 | | 文件附件 | Claude 是将附加文件直接传递给 MCP，还是 DeckFlow 需要上传 URL。 | | 权限提示 | 用户是否可以将 DeckFlow 工具设置为“始终允许”。 | | 输出链接 | 临时下载链接已确认；确认签名 URL 的有效期。 | ## 待确认的参数 | 参数 | 问题 | | --- | --- | | 连接器名称 | 应将其记录为 `DeckFlow`、`deckflow` 还是其他显示名称？ | | API 密钥传输 | Claude 自定义连接器能否安全地发送 DeckFlow API 密钥，用户又该如何配置它？ | | 界面截图 | 我们是否有特定的 DeckFlow Claude 截图需要包含？ | | 套餐要求 | 应该列出哪些 Claude 和 DeckFlow 套餐？ | --- ## [ZH] MCP 待确认的问题清单 **URL:** `https://app.deckflow.com/docs/zh/mcp/confirmation-questions.md` # MCP 待确认的问题清单 > 在将 MCP 文档占位符替换为最终参数前，需要向 DeckFlow 产品/API 负责人确认的问题。 在 MCP 开发文档由草案状态转为正式的生产就绪参考手册前，请先答复这些问题。 ## 目前已确认的事项 | 事项领域 | 已确认的取值 | | --- | --- | | MCP 端点 | `https://dev.deckflow.com/mcp/v1/` | | 身份验证方式 | 仅限 API 密钥 | | 首批支持客户端 | `claude-code`, `claude-web`, `manus`, `open-ai` | | 文件交付方式 | 临时签名下载链接 | ## 1. 接口端点与传输协议 1. `https://dev.deckflow.com/mcp/v1/` 是公开的生产端点，还是开发/测试端点？ 2. 是否存在预发（Staging）、区域级或额外的版本化端点？ 3. 示例中是否应始终包含尾部斜杠？ 4. DeckFlow 是否仅支持远程 HTTP MCP，还是也将提供 SSE、stdio 或本地服务器支持？ 5. 规范的 MCP 配置键名应该是 `deckflow`、`DeckFlow` 还是其他名称？ ## 2. 身份验证 1. 用户在何处创建或复制 DeckFlow API 密钥？ 2. 客户端在发送 API 密钥时应该使用哪个 HTTP 请求头、机密字段或环境变量？ 3. 文档中应该使用统一的环境变量（如 `DECKFLOW_API_KEY`），还是仅使用客户端专用的机密配置项？ 4. API 密钥是个人级别的、工作区级别的、组织级别的还是项目级别的？ 5. 用户如何撤销或轮换 DeckFlow API 密钥？ ## 3. 官方客户端支持 1. 确认发布文档中是否仅应包含 Claude Code、Claude Web/Desktop、Manus 和 OpenAI/ChatGPT？ 2. 虽然 HeyGen 仅在概述中提及 Cursor，但后续是否需要为 Cursor 提供专用的指南页面？ 3. 是否有任何客户端在调用时需要域名白名单、应用注册或私测（Private Beta）准入资格？ 4. 哪些客户端接入页面在发布前需要附带配置界面截图？ ## 4. 工具命名规范 1. `create_deck`、`revamp_deck` 和 `translate_deck` 是否为最终确定的工具名称？ 2. 单点工具（Tools）是应该使用分组后的工具（如 `convert_file`、`extract_file_content`、`compose_files` 和 `optimize_file`），还是每个网页端工具对应一个 MCP 工具？ 3. 最终的任务工具名称是什么：`get_task`、`list_tasks`、`cancel_task` 和 `get_task_result`，还是其他名称？ 4. `get_deckflow_capabilities` 是否为首选的能力发现工具名称？ 5. 是否需要提供 `get_current_user`、`list_brand_profiles`、`list_templates`、`list_glossaries` 和 `list_supported_languages` 等工具？ ## 5. 文件输入与输出 1. 智能体应该如何传递文件：MCP 附件、DeckFlow 上传 ID、预签名上传 URL、外部 URL、内联内容，还是混合方式？ 2. 智能体能否从终端客户端直接传递本地文件路径，还是必须先进行上传？ 3. 输入文件在服务器上保留多长时间？ 4. 临时下载链接已确认，但签名的 URL 有效期是多久？ 5. 输出文件是否也会持久保存在 DeckFlow 工作区中，还是仅通过临时链接提供？ ## 6. 任务生命周期 1. 任务的状态枚举是什么？ 2. 是否每个任务都返回进度百分比、阶段名称、预估剩余时间（ETA），还是仅返回状态？ 3. 哪些任务支持取消？ 4. 是否支持幂等性键以防止重复提交任务？ 5. 规范的错误 Schema 是什么？ ## 7. 产品工作流参数 1. Create 的最终输入源类型和输出格式是什么？ 2. 对于幻灯片数量、长宽比、语言、品牌 DNA、模板以及复杂元素保留，应该存在哪些 Create 参数？ 3. 对于样式模式、模板、品牌 DNA、内容保留、批量模式以及输出格式，应该存在哪些 Revamp 参数？ 4. 对于目标语言、源语言、术语表、排版保留、同格式输出以及图片文本翻译，应该存在哪些 Translate 参数？ 5. 哪些参数是必填的、选填的，或者由 DeckFlow 提供默认值？ ## 8. 限制与计费 1. MCP 工作流是否使用与公开的网页端工具相同的文件大小限制？ 2. 单次任务的最大文件数、总批量大小、幻灯片页数、总页数、视频时长以及内联提示词的最大长度是多少？ 3. 速率限制和并发任务限制是多少？ 4. 哪些 DeckFlow 套餐包含 MCP 接入权限？ 5. 针对成功、失败、已取消或部分成功的任务，额度是如何扣减的？ ## 9. 安全与合规 1. 文档是否也应该声明对 MCP 上传的文件进行 AES-256 加密以及在处理完成后进行删除？ 2. MCP 输入文件是否会用于模型训练？ 3. 是否存在针对 MCP 任务创建和下载的工作区审计日志？ 4. 是否有启用/禁用 MCP 的管理员控制选项？ 5. 是否出于安全原因封禁了某些文件类型或域名？ ## 10. 发布事宜 1. 哪些占位符现在可以进行替换？ 2. 哪些页面在集成上线前应保持仅限内部可见？ 3. 示例中应该包含真实的屏幕截图，还是先提供纯文本配置说明？ 4. 文档中应当使用 `OpenAI`、`ChatGPT` 还是 `OpenAI / ChatGPT` 作为页面标题？ 5. 谁来签字批准端点、计费和保留期相关的措辞？ --- ## [ZH] MCP 示例场景 **URL:** `https://app.deckflow.com/docs/zh/mcp/examples.md` # MCP 示例场景 > AI 智能体使用 DeckFlow MCP 的提示词示例与期望工具调用流。 以下示例均作为产品文档草案编写。在最终的 MCP Schema 规范确定前，工具名称及参数皆为占位符。 ## 根据研究资料生成演示文稿 用户提示词： ```text 使用 DeckFlow 将这份 PDF 研究报告生成为一个 12 页的投资路演幻灯片。保持技术图表清晰易读，使用简洁的决策层语气，并导出为 PPTX 格式。 ``` 智能体期望的工作流： 1. 确认附件文件是支持的创建 (`Create`) 数据源。 2. 调用 `create_deck` 工具，传入源文件、要求的幻灯片页数、目标受众、语气和 `PPTX` 输出格式。 3. 轮询调用 `get_task`，直至任务执行完成。 4. 返回 `PPTX` 临时签名下载链接，并指出任何告警信息（如缺失字体或图表失真问题）。 用户或智能体应当提供的参数： | 参数 | 示例值 | | --- | --- | | `source_type` | `file` | | `source` | 随附的 PDF 文件 | | `slide_count` | `12` | | `audience` | `investors` | | `tone` | `executive, concise` | | `output_format` | `pptx` | ## 根据网页链接 (URL) 生成演示文稿 用户提示词： ```text 根据这个网页链接生成一个简短的产品概述演示文稿，并同时导出为 PPTX 和 PDF。 ``` 智能体期望的工作流： 1. 检查当前是否支持 URL 链接导入功能。 2. 调用 `create_deck`，传入参数 `source_type=url`。 3. 如果支持单次任务返回多种格式则直接请求；否则在创建完成后依次调用导出工具。 4. 返回生成的这两个临时签名下载链接。 待确定的参数： | 参数 | 待确认的开放问题 | | --- | --- | | `source_url` | 是仅支持公开网页 URL，还是也支持导入需要登录验证的页面？ | | `output_format` | 单个任务能否同时返回多种输出文件格式？ | | `crawl_depth` | 网页导入是仅限单页，还是能顺着链接爬取子页面？ | ## 翻新现有演示文稿 用户提示词： ```text 使用 DeckFlow 并应用我们已保存的品牌 DNA 配置翻新这份 PPTX 演示文稿。不要重写其文字内容。保持最终输出文件为可编辑格式。 ``` 智能体期望的工作流： 1. 如果用户未指定品牌 DNA 配置，则调用 `list_brand_profiles`。 2. 调用 `revamp_deck`，传入所选的品牌配置和 `preserve_content=true`。 3. 轮询任务状态。 4. 以临时下载链接的形式返回可编辑的输出文件。 用户或智能体应当提供的参数： | 参数 | 示例值 | | --- | --- | | `file` | 随附的 PPTX 文件 | | `style_mode` | `brand_dna` | | `brand_profile_id` | 所选的配置 ID | | `preserve_content` | `true` | | `output_format` | `pptx` | ## 保留排版版式进行翻译 用户提示词： ```text 将此 Keynote 演示文稿翻译为日语。保持排版完整，并使用我们的产品术语表。 ``` 智能体期望的工作流： 1. 验证是否支持 Keynote 文件输入。 2. 如果用户未指明术语表 ID，则调用 `list_glossaries`。 3. 调用 `translate_deck`，传入目标语言和术语表。 4. 轮询直至任务完成。 5. 以临时下载链接的形式返回翻译后的文件，以及任何排版相关的警告信息。 用户或智能体应当提供的参数： | 参数 | 示例值 | | --- | --- | | `file` | 随附的 Keynote 文件 | | `target_language` | `ja` | | `glossary_id` | 所选的术语表 ID | | `preserve_layout` | `true` | | `output_format` | 如果支持，与输入格式相同 | ## 将 HTML 转换为 PPTX 用户提示词： ```text 使用 DeckFlow 将此 HTML 页面转换为可编辑的 PowerPoint 演示文稿。 ``` 智能体期望的工作流： 1. 使用 `convert_file`，传入 `operation=html_to_pptx`。 2. 传递上传的 HTML 文件或粘贴的 HTML 内容。 3. 以临时下载链接的形式返回生成的 PPTX。 用户或智能体应当提供的参数： | 参数 | 示例值 | | --- | --- | | `operation` | `html_to_pptx` | | `file` 或 `content` | HTML 文件或粘贴的 HTML 内容 | | `output_format` | `pptx` | ## 从 PPTX 中提取文本形状 用户提示词： ```text 提取此 PPTX 第 3 至 10 页的所有文本框，并返回结构化的 JSON 数据。 ``` 智能体期望的工作流： 1. 调用 `extract_file_content`，传入 `operation=pptx_text_extractor`。 2. 将 `page_range` 或 `slide_range` 设置为幻灯片 3 到 10。 3. 请求结构化输出。 4. 返回内联 JSON 或可下载的 JSON 文件。 待确定的参数： | 参数 | 待确认的开放问题 | | --- | --- | | `page_range` 与 `slide_range` | API/MCP 应该统一使用哪个名称？ | | `include_coordinates` | 默认情况下是否应该返回形状位置坐标？ | | `output_format` | 是返回内联 JSON 响应，还是生成可下载的 JSON 文件？ | ## 合并多个 PPTX 文件 用户提示词： ```text 按照上传顺序合并这三个 PPTX 文件。尽可能保留每个演示文稿的原始格式。 ``` 智能体期望的工作流： 1. 保留上传顺序，或请求用户确认排序。 2. 调用 `compose_files`，传入 `operation=pptx_merge` | 3. 轮询直至任务完成。 4. 以临时下载链接的形式返回合并后的演示文稿。 用户或智能体应当提供的参数： | 参数 | 示例值 | | --- | --- | | `operation` | `pptx_merge` | | `files` | 有序的 PPTX 文件引用列表 | | `preserve_styles` | `true` | | `output_name` | 可选的文件名 | ## 压缩交付包体积 用户提示词： ```text 压缩此 PPTX 文件以便我可以通过邮件发送，但要保持高图片质量。 ``` 智能体期望的工作流： 1. 调用 `optimize_file`，传入 `operation=file_compress`。 2. 选择一个保守的压缩预设。 3. 以临时下载链接的形式返回压缩后的文件，并在可用时返回压缩前后的文件大小。 待确定的参数： | 参数 | 待确认的开放问题 | | --- | --- | | `quality` | 预设枚举值还是数值？ | | `target_size_mb` | 用户是否应该能够请求最大限制体积？ | | `size_report` | 结果中是否应该包含前后字节大小对比？ | ## 智能体行为规范 智能体应在以下情况下提出追加提问： - 缺失源文件。 - 用户请求了品牌 DNA 配置、模板或术语表，但未指明具体是哪一个，且不存在默认配置。 - 输出格式不受支持或含糊不清。 - 任务执行可能会覆盖或删除现有的工作区资产。 - 附加了多个文件且文件顺序至关重要。 智能体应当在以下情况下直接执行，无需追加提问： - 用户附加了恰好一个兼容的文件。 - 请求的操作和输出格式清晰明确。 - 可以通过 `get_deckflow_capabilities` 发现 DeckFlow 的各项能力。 - 最终的 Schema 中定义了合理的默认值。 ## 能力发现示例 Prompt ```text 使用 DeckFlow MCP 检查可用的能力，然后告诉我哪些操作支持 PPTX 输入，以及每个操作可以生成哪些输出格式。 ``` 智能体期望的工作流： 1. 调用 `get_deckflow_capabilities`。 2. 筛选输入格式中包含 PPTX 的能力。 3. 总结支持的输出格式及限制。 --- ## [ZH] Manus **URL:** `https://app.deckflow.com/docs/zh/mcp/manus.md` # Manus > 将 DeckFlow 连接到 Manus 智能体，使自动化的工作流可以直接创建、翻新、翻译、转换和优化演示文稿文件，无需人工手动交接。 本页面参考了主流连接配置的结构，并使用已确认 of DeckFlow 端点、仅限 API 密钥的身份验证模型、首批支持客户端以及输出临时下载链接的逻辑。最终的 Manus 集成路径取决于 DeckFlow 是作为 Manus 内置的原生工具还是通过自定义 MCP 端点进行添加。相关细节仍待后续确认。 ## 前提条件 - 具备智能体 (Agent) 访问权限的 Manus 账户。 - 具备 MCP 访问权限的 DeckFlow 账户。 - 一个 DeckFlow API 密钥（除非 Manus 的集成方案支持通过托管连接器存储密钥）。 - 在 Manus 中已确认的 DeckFlow 集成路径。 - 上传或引用智能体所使用源文件的权限。 ## 连接 DeckFlow 针对 Manus 特定 UI 的连接路径目前待定 (TBD)，但已确认的 DeckFlow MCP 端点为： ```text https://dev.deckflow.com/mcp/v1/ ``` 如果 DeckFlow 作为 Manus 内置工具可用： 1. 打开 Manus。 2. 进入 **连接工具** (Connect Your Tools)。 3. 搜索 `DeckFlow`。 4. 点击 **连接** (Connect)。 5. 如果托管连接器要求，请输入配置的 DeckFlow API 密钥。 如果 Manus 需要配置自定义 MCP 端点： 1. 打开 Manus 的工具或集成设置页面。 2. 添加一个名为 `DeckFlow` 的自定义 MCP 服务器。 3. 将端点设置为 `https://dev.deckflow.com/mcp/v1/`。 4. 使用 Manus 支持的机密管理或连接器流程配置 DeckFlow API 密钥。 ## 在 Manus 智能体中使用 DeckFlow 打开智能体工作区，为智能体勾选启用 DeckFlow 工具。然后使用自然语言描述您希望执行的工作流任务。 提示词示例如下： ```text 每逢周一早上，收集工作区内最新的产品更新笔记，使用 DeckFlow 生成一份简洁的内部更新演示文稿，并导出为 PPTX 和 PDF，然后将临时下载链接发送给我。 ``` Manus 会编排源文件收集，提交 DeckFlow 任务，监控进度并交付结果包。 ## 定时与无人值守工作流 Manus 类型的智能体非常适合用于执行周期性的 DeckFlow 任务： - 从笔记或报告中生成每周的状态演示文稿。 - 为区域团队翻译销售演示文稿。 - 使用最新的企业品牌 DNA 翻新旧演示文稿。 - 在发送给客户前压缩交付包体积。 - 提取 PPTX 文本或字体使用情况以进行审查。 最终文档应说明 DeckFlow MCP 是否允许无人值守执行，以及 API 密钥范围、文件保留期和计费如何针对定时智能体运行。 ## 推荐给智能体的指令 ```text 在使用 DeckFlow 之前，确认工作流类型、输入文件、输出格式和目标工作区。对于定时任务，报告任务 ID、警告、输出链接和任何失败的文件。 ``` ## 待确认的参数 | 参数 | 问题 | | --- | --- | | Manus 路径 | DeckFlow 是 Manus 的内置工具、自定义 MCP 连接器，还是两者皆有？ | | API 密钥传输 | Manus 如何存储和发送 DeckFlow API 密钥？ | | 定时任务 | DeckFlow 的策略是否支持周期性/无人值守任务？ | | 输出交付 | 临时下载链接已确认。Manus 是直接附加文件还是也需要将输出保存到 DeckFlow 工作区？ | --- ## [ZH] OpenAI / ChatGPT **URL:** `https://app.deckflow.com/docs/zh/mcp/open-ai.md` # OpenAI / ChatGPT > 将 DeckFlow 添加到 ChatGPT 或 OpenAI 智能体界面，使用户可以直接在对话中调用演示文稿和文件处理工作流。 本页面参考了主流连接配置的结构，并使用已确认 of DeckFlow 端点、仅限 API 密钥的身份验证模型、首批支持客户端以及输出临时下载链接的逻辑。具体的配置步骤取决于 DeckFlow 是以 ChatGPT 应用（App）、自定义 MCP 连接器还是 OpenAI 智能体工具集成的形式发布。相关细节仍待后续确认。 ## 前提条件 - 具备目标应用/工具集成界面访问权限的 ChatGPT 或 OpenAI 账户。 - 具备 MCP 访问权限 of DeckFlow 账户。 - 一个 DeckFlow API 密钥（除非应用集成方案已托管密钥存储）。 - 在 OpenAI 中已确认的 DeckFlow 集成路径。 - 上传或引用演示文稿、文档、图片、HTML 或视频文件的权限。 ## 接入配置选项 A：DeckFlow 应用 (App) 如果 DeckFlow 作为 ChatGPT 应用（App）发布，请使用此路径。 1. 打开 ChatGPT。 2. 进入应用 (Apps) 或连接器 (Connectors) 区域。 3. 搜索 `DeckFlow`。 4. 选择官方的 DeckFlow 应用。 5. 点击 **连接** (Connect)。 6. 如果应用要求，请输入配置的 DeckFlow API 密钥。 发布后，最终的文档应该包含官方应用的 URL。 ## 接入配置选项 B：自定义 MCP 连接器 如果 ChatGPT 或目标 OpenAI 平台支持自定义 MCP 连接器，请使用此路径。 1. 打开连接器设置。 2. 添加一个名为 `DeckFlow` 的自定义连接器。 3. 将远程 MCP 端点设置为： ```text https://dev.deckflow.com/mcp/v1/ ``` 1. 保存连接器。 2. 使用 OpenAI/ChatGPT 支持的机密管理或连接器流程配置 DeckFlow API 密钥。 ## 使用方法 提示词示例如下： ```text 使用 DeckFlow 并应用我们默认的品牌 DNA 配置翻新这份销售演示文稿，保留其文字内容不变，最后返回一个可编辑的 PPTX 文件。 ``` 智能体应当调用 DeckFlow 工具，监控异步任务，并以临时下载链接的形式返回生成的结果。 ## 优质的 Prompt 模式 - 包含源文件或 URL。 - 指定工作流名称：Create、Revamp、Translate、Convert、Extract、Merge、Split 或 Optimize。 - 指定输出格式，如 PPTX、PDF、PNG、WebP、HTML、MP4、JSON 或 ZIP。 - 提及设计或语言限制，如品牌 DNA、模板、目标语言或术语表。 - 要求智能体在布局、字体、图表或图片需要注意时报告警告信息。 ## 待确认的参数 | 参数 | 问题 | | --- | --- | | OpenAI 界面 | DeckFlow 是面向 ChatGPT Apps、自定义 MCP、助手/智能体 (Assistants/Agents) 还是多个界面？ | | 应用 URL | 官方 ChatGPT 应用的 URL 是什么（如果有的话）？ | | API 密钥传输 | OpenAI/ChatGPT 应当如何将 DeckFlow API 密钥发送给 MCP？ | | 文件附件 | ChatGPT 能否将附加文件直接传递给 DeckFlow，或者 DeckFlow 是否需要一个单独的上传步骤？ | | 套餐要求 | 需要哪些 OpenAI/ChatGPT 以及 DeckFlow 的套餐？ | --- ## [ZH] MCP 参数清单 **URL:** `https://app.deckflow.com/docs/zh/mcp/parameter-checklist.md` # MCP 参数清单 > 在 DeckFlow MCP 文档成为最终的工具文档之前，需要确定的产品/API 决策。 本页面收集了在起草 `index.md`、`setup.md`、`tools.md` 和 `examples.md` 时发现的缺失参数。 若要查看直接向产品/API 所有者确认的问题，请参阅 `confirmation-questions.md`。 ## 已确认的数值 | 领域 / 模块 | 已确认的数值 | | --- | --- | | MCP 端点 | `https://dev.deckflow.com/mcp/v1/` | | 身份验证 | 仅限 API 密钥 | | 首批客户端 | Claude Code, Claude 网页端/桌面端, Manus, OpenAI/ChatGPT | | 输出交付 | 临时下载链接 | ## 连接配置 | 参数 / 概念 | 待确定的定义 | | --- | --- | | MCP 端点 | 确定 `https://dev.deckflow.com/mcp/v1/` 是生产环境还是开发/测试环境，以及确定环境发布、区域和版本控制策略。 | | 传输协议 | 仅限远程 HTTP、支持 SSE、stdio/本地服务器支持，或支持多种模式。 | | 服务器名称 | 规范的配置键名：`deckflow`、`DeckFlow` 或其他名称。 | | 能力发现 | 是否提供 `get_deckflow_capabilities` 工具，以及它的返回结果结构。 | ## 身份验证与权限 | 参数 / 概念 | 待确定的定义 | | --- | --- | | 身份验证方式 | 已确认仅使用 API 密钥。仍需确定密钥创建页面 URL、请求头或环境变量名称，以及针对特定客户端的密钥处理方式。 | | API 密钥权限范围 | 如果存在分层级权限密钥，需要确定：文件上传、任务创建、任务读取、工作区读取、术语表读取、`Brand DNA` 读取、计费读取等范围。 | | 工作区范围 | 确定是个人账户、团队工作区、组织还是项目级别。 | | 令牌生命周期 | 确定过期、刷新、重新连接、注销及撤销逻辑。 | | 域名/应用白名单 | 自定义智能体是否需要域名白名单或应用注册流程。 | | 用户身份识别工具 | 当前用户/账户查询的最终工具名称和响应结构。 | ## 文件输入 | 参数 / 概念 | 待确定的定义 | | --- | --- | | 文件引用模型 | `file_id`、`asset_id`、签名上传 URL、客户端附件 ID、外部 URL 或内联内容。 | | 上传限制 | 最大大小、每次任务最大文件数、总批量大小、页数、幻灯片数、视频时长。 | | 支持的 MIME 类型 | 针对每个工作流的规范 MIME 和扩展名列表。 | | URL 导入 | 仅支持公开 URL、经身份验证的 URL、允许的域名、爬取深度和超时时间。 | | 内联内容 | 粘贴的 HTML、Markdown、文本和提示词字段的最大长度。 | | 保留策略 | 上传的输入文件存储多长时间以及何时删除。 | ## 通用任务生命周期 | 参数 / 概念 | 待确定的定义 | | --- | --- | | 任务 ID | 格式、稳定性、工作区可见性和过期时间。 | | 状态枚举 | 排队中、处理中、成功、失败、已取消和已过期的规范状态。 | | 进度 | 百分比、阶段标签、预估剩余时间 (ETA)、当前步骤，或不提供进度。 | | 取消操作 | 哪些工具支持取消以及何时允许取消。 | | 重试行为 | 客户端重试规则、幂等性键支持以及重复任务预防。 | | Webhook | MCP 任务是可以注册回调，还是仅支持轮询。 | | 错误 Schema | 错误代码、错误消息、可重试标志、字段级校验错误以及支持追踪 ID。 | ## 输出交付 | 参数 / 概念 | 待确定的定义 | | --- | --- | | 结果模型 | 文件、预览图、元数据、警告、日志和嵌套资产。 | | 下载 URL | 临时签名 URL 的有效时间、访问控制、文件名和内容类型。 | | 多个输出 | PPTX + PDF 或图片批次是如何表示的。 | | ZIP 打包 | 多文件输出何时打包为 ZIP 以及用户如何请求。 | | 工作区持久化 | 输出是否会出现在 DeckFlow 网页端应用/项目库中。 | | 结果过期 | 输出在多长时间内保持可下载状态。 | ## Create（生成） | 参数 / 概念 | 待确定的定义 | | --- | --- | | `source_type` | 文件、URL、文本、Markdown、主题或混合源的枚举值。 | | `source` | 文件引用、URL、内联内容或多个数据源。 | | `prompt` | 最大长度、必填/选填行为以及提示词安全规则。 | | `output_format` | PPTX、PDF、HTML、图片，或者多种输出格式。 | | `slide_count` | 精确的幻灯片数、最小/最大范围，或由智能体评估的默认值。 | | `aspect_ratio` | 支持的长宽比和默认值。 | | `brand_profile_id` | 品牌 DNA ID 格式和默认品牌配置行为。 | | `template_id` | 模板目录、兼容性和预览支持。 | | `language` | 语言代码标准和自动检测行为。 | | 复杂元素处理 | 公式、图表、示意图、图像、表格和嵌套结构的默认处理方式。 | ## Revamp（焕新） | 参数 / 概念 | 待确定的定义 | | --- | --- | | 输入格式 | PPTX、Keynote、PDF，以及是否接受 PPT。 | | `style_mode` | 模板、品牌 DNA、自定义指令或自动样式。 | | `template_id` | 模板列表、筛选、预览和兼容性。 | | `brand_profile_id` | 品牌 DNA 的可用性、选择和回退。 | | `preserve_content` | 内容保留是强制执行的还是可配置的。 | | 批量焕新 | 最大文件数、排序方式、输出打包和单个文件失败处理。 | | 输出格式 | 与输入相同、仅 PPTX、PDF、Keynote 或是多种格式。 | ## Translate（翻译） | 参数 / 概念 | 待确定的定义 | | --- | --- | | 支持的语言 | 规范列表、语言代码、区域变体以及从右至左 (RTL) 书写支持。 | | `source_language` | 选填、必填或自动检测。 | | `target_language` | 必填字段格式。 | | 术语表模型 | `glossary_id`、内联词条、CSV 上传、词条大小写敏感度及优先级。 | | 排版保留 | 当翻译后的文本无法放下的默认和警告行为。 | | 同格式输出 | 是否始终保留输入格式，还是可以更改。 | | 图片文本翻译 | 图片内的 OCR 文本是否默认翻译。 | | 演讲者备注/批注 | 是否翻译备注和批注。 | ## 转换器工具 | 参数 / 概念 | 待确定的定义 | | --- | --- | | `operation` 枚举 | 13 个转换操作的最终名称。 | | HTML 渲染选项 | 视口、缩放比例、等待时间、外部资源、字体和页面高度行为。 | | PPT/视频选项 | 每张幻灯片的持续时间、动画处理、过渡处理、分辨率、FPS。 | | 图片输出选项 | PNG/JPEG/WebP、缩放比例、页面范围、ZIP 打包和命名。 | | 传统 PPT 处理 | 传统 PPT 输入是直接转换，还是先规范化为 PPTX。 | ## 提取器工具 | 参数 / 概念 | 待确定的定义 | | --- | --- | | OCR 语言 | 自动检测、语言提示和支持的文字系统。 | | OCR 输出 | 纯文本、JSON 块、坐标、置信度、阅读顺序。 | | PPTX 字体输出 | 字体族、样式、粗细、幻灯片使用情况、缺失字体检测。 | | PPTX 文本输出 | 形状 ID、幻灯片编号、坐标、样式元数据、演讲者备注。 | | 范围参数 | 统一为 `page_range`、`slide_range` 还是 `ranges`。 | ## 合并与拆分器 | 参数 / 概念 | 待确定的定义 | | --- | --- | | 合并顺序 | 上传顺序、显式顺序数组或按文件名排序。 | | 排版保留 | 主题、母版、字体和重复资源的处理方式。 | | 拆分策略 | 拆分每张幻灯片、选择的范围、固定块大小或命名小节。 | | HTML 播放器包 | 画布大小、标题、描述、导航和资源打包。 | | 部分失败 | 某个输入文件校验失败时的行为。 | ## 优化器 | 参数 / 概念 | 待确定的定义 | | --- | --- | | 压缩质量 | 预设值、数值范围、默认值和最低质量。 | | 目标大小 | 用户是否可以请求最大的 MB 输出以及无法满足时的处理。 | | 图片调整大小 | 宽度/高度规则、长宽比锁定、放大策略、输出类型。 | | 字体嵌入 | 字体文件上传、许可警告、子集化和字体选择。 | | 视频压缩 | 编解码器、码率、分辨率、FPS、音频处理和目标格式。 | ## 限制与计费 | 参数 / 概念 | 待确定的定义 | | --- | --- | | 套餐访问权限 | 哪些 DeckFlow 套餐可以使用 MCP。 | | 额度扣减 | 任务如何消耗额度，以及失败/取消的任务如何收费。 | | 速率限制 | 每分钟请求数、每小时任务数、并发作业数、批量限制。 | | 免费额度 | 是否提供 MCP 以及相应的限制。 | | 用量报告 | 智能体是否可以查询剩余额度或历史任务记录。 | ## 文档发布清单 - 确认 `https://dev.deckflow.com/mcp/v1/` 是最终的生产端点还是开发/测试端点。 - 确认最终工具名称并移除“规划中/建议的”措辞。 - 添加最终的 JSON Schema 或链接到生成的参考页面。 - 仅在集成完成后添加真实的客户端屏幕截图。 - 与产品/法务确认安全、数据保留、计费和套餐的措辞。 - 在发布前对照可运行的 MCP 服务器验证示例。 --- ## [ZH] MCP 接入配置 **URL:** `https://app.deckflow.com/docs/zh/mcp/setup.md` # MCP 接入配置 > 在 AI 客户端中配置 DeckFlow MCP，使智能体能够直接从聊天、代码或自动化智能体进程中调用演示文稿和文件处理工作流。 本页面是一个配置草案。它参考了主流配置指南的结构，并使用已确认的 DeckFlow 端点、仅限 API 密钥的身份验证模型、首批支持客户端以及输出临时下载链接的逻辑。 ## 前提条件 - 一个 DeckFlow 账户。 - 获得 DeckFlow MCP 测试或生产集成权限。 - 一个支持远程 HTTP MCP 服务器的兼容 MCP 客户端。 - 一个 DeckFlow API 密钥。 - 上传或引用 `Create`、`Revamp`、`Translate` 以及 `Tools` 工作流中所使用源文件的权限。 ## MCP 端点 ```text https://dev.deckflow.com/mcp/v1/ ``` 当前文档均统一使用该端点。后续请进一步确认这究竟是最终的生产环境 URL，还是开发测试环境端点。 ## 客户端专有配置指南 针对特定客户端的详细配置流程，请参阅对应页面： | 客户端 | 接入配置指南 | | --- | --- | | Claude Code | `claude-code.md` | | Claude 网页端 / 桌面端 | `claude-web.md` | | Manus | `manus.md` | | OpenAI / ChatGPT | `open-ai.md` | 本页面作为通用 MCP 配置的共享概述和备用指南。 ## 身份验证 DeckFlow MCP 仅使用 API 密钥进行身份验证。 最终的配置指南仍需确定以下关于 API 密钥的配置信息： | API 密钥配置明细 | 最终文档必须说明的内容 | | --- | --- | | 密钥创建 URL | 用户在何处创建或复制 DeckFlow API 密钥。 | | 密钥名称 | 客户端应使用 `Authorization` 请求头（以 `Bearer ` 形式）。 | | 传输方式 | 密钥是通过 MCP 客户端的机密配置（`secret config`）、HTTP 请求头配置，还是通过身份验证提示进行传递。 | | 权限范围 | 密钥是个人账户、工作区级、组织级还是项目级。 | | 密钥轮换 | 用户如何撤销或轮换密钥。 | ## Claude Code 在终端中运行以下命令（在 Claude Code 交互式会话之外）： ```bash claude mcp add --transport http deckflow https://dev.deckflow.com/mcp/v1/ ``` 要在全局所有 Claude Code 项目中安装它： ```bash claude mcp add --transport http -s user deckflow https://dev.deckflow.com/mcp/v1/ ``` 添加服务器后，请重启 Claude Code 或运行客户端专用的 MCP 刷新命令（如果可用）。 ### 备选配置 如果目标 Claude Code 版本支持直接编辑配置文件，其 MCP 服务器配置应如下所示： ```json { "mcpServers": { "deckflow": { "type": "http", "url": "https://dev.deckflow.com/mcp/v1/" } } } ``` ## Claude 网页端 / 桌面端 1. 打开连接器（Connector）或集成设置。 2. 添加一个名为 `DeckFlow` 的自定义连接器。 3. 将远程 MCP 服务器 URL 设置为： ```text https://dev.deckflow.com/mcp/v1/ ``` 1. 保存连接器。 2. 使用 Claude 支持的机密（secret）或连接器流程配置 DeckFlow API 密钥。 3. 当客户端请求工具权限时，允许 DeckFlow 工具。 ## 其他 MCP 客户端 首批确认的 DeckFlow 客户端列表是 Claude Code, Claude Web/Desktop, Manus, 和 OpenAI/ChatGPT。在产品支持确认后，可以按照以下通用模式记录其他兼容 MCP 的客户端。 对于接受 JSON 格式 MCP 服务器定义的客户端，使用相同的远程 HTTP 结构： ```json { "mcpServers": { "deckflow": { "type": "http", "url": "https://dev.deckflow.com/mcp/v1/" } } } ``` 如果客户端使用不同的字段名称，请将最终端点映射到其远程 MCP URL 字段中。 ## 验证连接 使用 MCP 客户端的服务器列表或工具发现命令来确认： - `deckflow` 服务器出现在已连接服务器列表中。 - DeckFlow 工具可见。 - 客户端可以访问有效的 DeckFlow API 密钥。 - 简单的账户或能力检查成功（如果 DeckFlow 提供了的话）。 建议的验证工具（如果实现）： ```text get_current_user ``` 或： ```text get_deckflow_capabilities ``` 在定义最终的工具 Schema 之前，这两个名称均为占位符。 ## 首选 Prompt 安装配置完成后，使用低风险任务进行测试： ```text 使用 DeckFlow 列出可用的 MCP 功能，并告诉我 Create、Revamp、Translate 和文件转换分别支持哪些文件格式。 ``` 接着测试文件处理工作流： ```text 使用 DeckFlow 将此 PowerPoint 演示文稿转换为 PDF 并返回临时下载链接。 ``` ## 客户端权限说明 MCP 客户端在每次调用工具之前可能会要求权限。为了获得更顺畅的体验，用户通常可以允许 DeckFlow 工具在当前对话、项目或工作区中始终运行。 最终文档应仔细解释权限范围，因为 DeckFlow 工具可以上传文件、创建派生文件并返回可下载的输出。 ## 待确定的配置参数 在 MCP 文档达到可实施状态之前，必须确定以下决策： | 参数 | 发布前必填内容 | | --- | --- | | 端点语义 | `https://dev.deckflow.com/mcp/v1/` 是公共生产端点还是开发/测试端点。 | | 服务器名称 | 确认 `deckflow` 作为规范的配置键。 | | API 密钥传输 | 请求头名称、环境变量名称、机密字段名称以及客户端专有的配置机制。 | | 账户范围 | 个人工作区、团队工作区、组织选择或项目选择。 | | 工具权限策略 | 针对在工具调用前进行提示的客户端，推荐的允许/拒绝设置。 | | 文件上传路径 | 文件是通过 MCP 上传、通过 URL 导入，还是通过客户端附件传递。 | | 连接测试 | 最终的健康/账户/能力测试工具名称。 | | 支持的客户端 | 哪些客户端是官方支持的，哪些是通用兼容的。 | 关于直接的产品/API 问题，请参阅 `confirmation-questions.md`。 --- ## [ZH] MCP 工具 **URL:** `https://app.deckflow.com/docs/zh/mcp/tools.md` # MCP 工具 > 面向 AI 智能体的 DeckFlow MCP 工具目录草案。以下列出的工具名称与 Schema 结构为规划性质的文档脚手架，并非最终的开发契约。 DeckFlow MCP 旨在同时提供产品级工作流与单用途的文件处理工具。其中最核心的设计决策是：最终的 MCP 服务器是采用大量职责单一的细粒度工具，还是采用较少、带有操作枚举的通用工具。 对于智能体接入，推荐的方案是：为 `Create`、`Revamp` 和 `Translate` 设计一组小巧的工作流工具，另外为文件转换、内容提取、合并/拆分和优化分别设计分组后的通用工具。这能让 MCP API 界面清晰易读，同时覆盖全部 23 种公开网页端工具。 ## 通用任务模型 大多数 DeckFlow 操作都应首先返回一个任务对象，然后由智能体轮询状态并获取处理结果。 | 规划工具名称 | 功能描述 | | --- | --- | | `get_task` | 获取任务的执行状态、进度、告警信息、错误明细和结果元数据。 | | `list_tasks` | 列出当前已验证身份的用户或工作区的历史任务。 | | `cancel_task` | 取消排队中或运行中的任务（在工具支持时）。 | | `get_task_result` | 获取已完成任务的输出文件、预览图、临时下载链接和元数据。 | ### 待确定的通用参数 | 参数 | 用途 | 待确认的决策 | | --- | --- | --- | | `task_id` | 唯一标识一个异步任务。 | ID 的格式规范、可见性范围和过期时间。 | | `status` | 表示任务生命周期状态。 | 包含 `queued`、`running`、`succeeded`、`failed`、`cancelled`、`expired` 的枚举值。 | | `progress` | 指示完成进度。 | 包含百分比数值、阶段步骤名称、预估剩余时间中的一种或全部。 | | `result_urls` | 提供生成文件临时下载链接。 | 签名 URL 的有效期以及文件是否持久化存储在工作区中。 | | `warnings` | 报告非致命问题。 | 包含缺失字体、布局调整、不支持的媒体等的警告代码。 | | `error` | 报告失败原因。 | 错误 Schema、是否可重试、面向用户的消息以及开发者错误码。 | ## 产品工作流工具 ### Create（生成） | 规划工具名称 | 功能描述 | | --- | --- | | `create_deck` | 从上传的文件、URL、粘贴的文本、Markdown 或主题提示词生成演示文稿。 | 预期输入参数： | 参数 | 描述 | 状态 | | --- | --- | --- | | `source_type` | 输入类型，如 `file`、`url`、`text`、`markdown` 或 `topic`。 | 需要枚举。 | | `source` | 文件引用、URL 或文本负载。 | 需要文件引用模型。 | | `prompt` | 用户对结构、受众、语气和侧重点的说明。 | 需要最大长度限制。 | | `output_format` | PPTX、PDF、HTML 或图片。 | 需要枚举和默认值。 | | `brand_profile_id` | 可选，要应用的品牌 DNA 配置。 | 需要品牌 DNA 模型。 | | `theme_or_template_id` | 可选，模板或设计风格。 | 需要模板目录。 | | `slide_count` | 期望的幻灯片数量或范围。 | 需要限制和默认值。 | | `aspect_ratio` | 演示文稿长宽比，如 16:9 或 4:3。 | 需要枚举。 | | `language` | 输出语言。 | 需要语言代码标准。 | | `preserve_complex_elements` | 是否保留公式、图表、图像和嵌套结构。 | 需要默认行为。 | ### Revamp（焕新） | 规划工具名称 | 功能描述 | | --- | --- | | `revamp_deck` | 在保留原始文本、数据和结构的前提下，重新设计现有演示文稿。 | 预期输入参数： | 参数 | 描述 | 状态 | | --- | --- | --- | | `file` | PPTX、Keynote 或 PDF 源演示文稿。 | 需要文件引用模型。 | | `style_mode` | `template` 或 `brand_dna`。 | 需要枚举。 | | `template_id` | 要应用的专业模板。 | 需要模板目录。 | | `brand_profile_id` | 要应用的品牌 DNA 配置。 | 需要品牌 DNA 模型。 | | `preserve_content` | 原始内容是否必须保持不变。 | 应该默认为 `true`。 | | `output_format` | 结果格式。 | 需要枚举；可能为同格式或 PPTX/PDF。 | | `batch_files` | 可选，用于批量焕新的多个演示文稿。 | 需要最大数量限制和结果打包机制。 | ### Translate（翻译） | 规划工具名称 | 功能描述 | | --- | --- | | `translate_deck` | 在保留排版的前提下翻译演示文稿和办公文档，返回相同或选择的输出格式。 | 预期输入参数： | 参数 | 描述 | 状态 | | --- | --- | --- | | `file` | PPTX、Keynote、PDF、Word 或 Excel 源文件。 | 需要文件引用模型。 | | `target_language` | 目标语言。 | 需要语言代码列表。 | | `source_language` | 可选，源语言。 | 需要自动检测行为。 | | `glossary_id` | 要应用的现有术语表。 | 需要术语表模型。 | | `glossary_terms` | 单次任务的内联术语表词条。 | 需要 Schema 和限制。 | | `preserve_layout` | 保留字体、大小、颜色、动画、图表、SmartArt、表格以及图片文本。 | 需要默认行为和失败处理行为。 | | `output_format` | 与输入相同或指定格式. | 需要枚举和默认值。 | | `formality` | 语气/正式度控制（如果支持）。 | 需要枚举或移除。 | ## 文件转换器工具 网页端工具页面列出了 13 个转换工具。MCP 可以将它们公开为一个分组后的工具： | 规划工具名称 | 功能描述 | | --- | --- | | `convert_file` | 将一个文件或文本类源从支持的输入格式转换为目标格式。 | 支持的操作候选： | 操作名称 | 输入 | 输出 | | --- | --- | --- | | `html_to_png` | HTML/HTM 文件或粘贴的 HTML | PNG | | `html_to_pptx` | HTML/HTM 文件或粘贴的 HTML | PPTX | | `image_to_webp` | 图片 | WebP | | `keynote_to_html` | Keynote | HTML | | `keynote_to_image` | Keynote | 图片 | | `keynote_to_pdf` | Keynote | PDF | | `markdown_to_image` | Markdown 文件或粘贴的 Markdown | 图片 | | `pdf_to_image` | PDF | 图片 | | `ppt_to_pptx` | PPT/PPTX | PPTX | | `powerpoint_to_pdf` | PPT/PPTX | PDF | | `powerpoint_to_image` | PPT/PPTX | 图片 | | `powerpoint_to_video` | PPT/PPTX | MP4 | | `word_to_pdf` | DOC/DOCX | PDF | 待确定的参数： | 参数 | 用途 | | --- | --- | | `operation` | 转换器操作枚举。 | | `file` | 上传的文件引用。 | | `content` | 未使用文件时粘贴的 HTML 或 Markdown。 | | `output_format` | 当操作支持多种输出时，显式指定输出类型。 | | `page_range` | 可选的页码或幻灯片范围。 | | `render_width` / `render_height` | 相关时的 HTML/图片/视频渲染大小。 | | `scale` | 图片渲染 density 或像素比。 | | `include_animations` | PPT 转视频时是否保留基本动画。 | | `zip_outputs` | 多文件图片输出是否应打包为 ZIP。 | ## 提取器工具 | 规划工具名称 | 功能描述 | | --- | --- | | `extract_file_content` | 从上传的文件中提取 OCR 文本、字体或 PPTX 文本形状。 | 支持的操作候选： | 操作名称 | 输入 | 输出 | | --- | --- | --- | | `image_ocr` | 图片 | 文本或结构化 OCR 结果 | | `pptx_font_finder` | PPTX | 字体列表 | | `pptx_text_extractor` | PPTX | 结构化文本形状 | 待确定的参数： | 参数 | 用途 | | --- | --- | | `operation` | 提取器操作枚举。 | | `file` | 上传的文件引用。 | | `languages` | OCR 语言提示。 | | `page_range` | 待检查的幻灯片或页码。 | | `include_coordinates` | 为 OCR 或 PPTX 文本形状返回文本框坐标。 | | `include_styles` | 在可用时返回字体族、大小、颜色和样式元数据。 | | `output_format` | JSON、CSV、TXT，或 ZIP（如果支持）。 | ## 合并与拆分器工具 | 规划工具名称 | 功能描述 | | --- | --- | | `compose_files` | 合并、拆分或打包演示文稿资源。 | 支持的操作候选： | 操作名称 | 输入 | 输出 | | --- | --- | --- | | `pptx_merge` | 多个 PPTX 文件 | 单个 PPTX | | `pptx_split` | 单个 PPTX | PPTX 文件的 ZIP 包 | | `html_player_pack` | 多个 HTML 文件 | 可播放的 HTML 播放包 | 待确定的参数： | 参数 | 用途 | | --- | --- | | `operation` | 合并/拆分/打包操作枚举。 | | `files` | 有序的文件引用列表。 | | `slide_ranges` | 包含或拆分所依据的范围。 | | `preserve_styles` | 是否保留源布局、字体和主题。 | | `canvas_width` / `canvas_height` | HTML 播放器的画布大小。 | | `title` | 可选的 HTML 播放器标题。 | | `description` | 可选的 HTML 播放器描述。 | | `output_name` | 期望的输出文件名。 | ## 优化器工具 | 规划工具名称 | 功能描述 | | --- | --- | | `optimize_file` | 在交付前压缩、调整大小或在文件中嵌入资源。 | 支持的操作候选： | 操作名称 | 输入 | 输出 | | --- | --- | --- | | `file_compress` | ZIP, PPTX, Keynote, DOCX, XLSX | 压缩后的文件 | | `image_resize` | 图片 | 调整大小后的图片 | | `pptx_embed_fonts` | PPTX 以及字体选择/文件 | PPTX | | `video_compress` | 视频 | 压缩后的视频 | 待确定的参数： | 参数 | 用途 | | --- | --- | | `operation` | 优化器操作枚举。 | | `file` | 上传的文件引用。 | | `quality` | 压缩质量预设或数值。 | | `target_size_mb` | 期望的最大输出大小。 | | `width` / `height` | 图片调整大小的尺寸。 | | `lock_aspect_ratio` | 保持原始图片的长宽比。 | | `font_files` | 要嵌入到 PPTX 中的字体文件。 | | `font_names` | 要嵌入或子集化的现有字体名称。 | | `video_codec` | 编解码器选择（如果支持）。 | | `video_bitrate` | 目标码率（如果支持）。 | ## 账户与能力工具 | 规划工具名称 | 功能描述 | | --- | --- | | `get_current_user` | 返回已验证身份的用户、工作区、套餐和使用情况详情。 | | `get_deckflow_capabilities` | 返回支持的工具、格式、限制、语言、模板和功能标志。 | | `list_brand_profiles` | 列出可用的品牌 DNA 配置。 | | `list_templates` | 列出可用于 Create 或 Revamp 的模板。 | | `list_glossaries` | 列出翻译术语表。 | | `list_supported_languages` | 列出支持的语言代码和名称。 | 这些工具可以减少硬编码文档，并帮助智能体在运行时选择有效的参数。 ## 网页端文件大小限制 | 工作流 / 工具 | 网页端限制 | | --- | --- | | 翻译产品工作流 | 最大 500 MB | | HTML 工具 | 50 MB | | Markdown 转图片 | 10 MB | | 图片 OCR | 50 MB | | 图片转 WebP / 图片调整大小 | 100 MB | | 大多数演示文稿/文档/视频工具 | 300 MB | 最终的 MCP 文档必须阐明，MCP 是采用与浏览器工具相同的限制，还是采用 API 限制，抑或是套餐专有的限制。 --- ========================================= LANGUAGE BUNDLE: EN ========================================= ## [EN] API Key **URL:** `https://app.deckflow.com/docs/en/guide/authentication.md` # API Key > Generate your DeckFlow API key from Settings. Use it to authenticate API requests, MCP integrations, CLI workflows, and server-side automation. DeckFlow uses API key authentication for developer access. The key is connected to the account or workspace where it was created, and usage from that key consumes the corresponding quota. ## Getting Your API Key 1. Log in to DeckFlow. 2. Open [**Settings**](https://app.deckflow.com/start#settings). 3. Go to the API key section. 4. Generate or copy your API key. Keep the key private. It can create jobs, access workspace resources, and consume Credit or Spark quota. ## Configuring Your API Key ### Environment variable (recommended) ```bash export DECKFLOW_API_KEY="Bearer " export DECKFLOW_API_BASE="https://app.deckflow.com/api" ``` ### .env file If your project uses a `.env` file, store the key outside your source code: ```text DECKFLOW_API_KEY="Bearer " DECKFLOW_API_BASE=https://app.deckflow.com/api ``` ### MCP and CLI For MCP clients, local agents, CI jobs, and CLI automation, set `DECKFLOW_API_KEY` before starting the workflow. ```bash export DECKFLOW_API_KEY="Bearer " # Start your MCP client, CLI command, or agent process after this. ``` In CI, store the key in your provider's secret manager. Do not paste API keys into prompts, notebooks, committed config files, or browser-only code. ## Using the Key in Requests All DeckFlow API requests authenticate with the `Authorization` header. ```bash curl -X POST "$DECKFLOW_API_BASE/tools/tasks" \ -H "Authorization: $DECKFLOW_API_KEY" ``` ```javascript const response = await fetch(`${process.env.DECKFLOW_API_BASE}/tools/tasks`, { method: "POST", headers: { "Authorization": process.env.DECKFLOW_API_KEY }, }); ``` ```python import os, requests response = requests.post( f"{os.environ['DECKFLOW_API_BASE']}/tools/tasks", headers={"Authorization": os.environ["DECKFLOW_API_KEY"]}, timeout=60, ) ``` ## Key Scope and Billing Requests are billed to the account or workspace associated with the API key. If the key is used by a server, CI job, MCP client, or CLI script, all jobs started by that environment consume the same workspace quota. For quota details, see [Pricing & Billing](./pricing-billing.md). ## Troubleshooting | Status | Meaning | What to check | | --- | --- | --- | | `401` | The key is missing, invalid, expired, or sent in the wrong header. | Confirm the `Authorization` header and copy the key again from [Settings](https://app.deckflow.com/start#settings). | | `403` | The key is valid but cannot access the requested workspace, feature, or resource. | Check workspace membership, plan permissions, and feature availability. | | `429` | The key is valid but the account is over a rate or quota limit. | Reduce concurrency or wait for quota recovery. | ## Security Best Practices - **Never commit your API key to version control.** Add `.env` to `.gitignore`. - **Never expose the key in client-side or browser code.** Call DeckFlow from a backend or trusted automation environment. - **Rotate keys when access changes.** Regenerate the key from [Settings](https://app.deckflow.com/start#settings) when a teammate leaves, a server is replaced, or a secret may have been exposed. - **Monitor usage in DeckFlow [Settings](https://app.deckflow.com/start#settings).** Review quota consumption for unexpected jobs or unusual traffic. --- ## [EN] Core Concepts **URL:** `https://app.deckflow.com/docs/en/guide/core-concepts.md` # Core Concepts > An introduction to DeckFlow core concepts, explaining the domain model shared across all API, MCP, and CLI documentation. DeckFlow provides a unified, developer-first platform for presentation generation, revamping, translation, and file utility processing. All operations run under the base URL `https://app.deckflow.com/api` and require authentication via the HTTP `Authorization` header. ## 1. Core Workflows DeckFlow features three primary product workflows along with a set of standalone file utilities: ### Create (Generation) Intelligently generates professional slides (PPTX) from raw sources: - **Supported Inputs**: Local documents (PDF, Word, Markdown), Web URLs, or plain text prompts. - **Controls**: Fine-tune generation using parameters like target slide count (`pageCount`), aspect ratio, target audience, author metadata, and toggle flags such as web search (`enableSearch`) or advanced reasoning models (`advancedModel`). ### Revamp (Redesign) Redesigns the visual style of existing decks while preserving their content, text, data, and layout hierarchy: - **Supported Inputs**: PPTX, Keynote, or PDF files. - **Styling Options**: Apply custom workspace **Brand DNA** guidelines or select from prebuilt professional templates. ### Translate Translates document layouts into different languages while preserving the typography, design, and animations: - **Supported Inputs**: PPTX, Keynote, PDF, Word, or Excel files. - **Custom Glossary**: Bind a custom terminology mapping (**Glossary**) to enforce consistent translation of brand names or specific technical terms. ## 2. Domain Entities ### Asynchronous Task (Task) All resource-heavy operations are driven by an asynchronous task pipeline: 1. **Task Submission**: Posting options to `POST /tools/tasks` immediately registers the request and yields a unique `taskId`. 2. **Task Status Polling**: Track progress using `GET /tools/tasks/{taskId}`. 3. **Task States**: - `queued`: Awaiting backend engine resource allocation. - `running`: Processing, rendering, or rewriting the file. - `completed`: Finished successfully. The final asset is available via `result.url`. - `failed`: Encountered errors. The reason is detailed in the `error` block. ### Quotas (Credit & Spark) Usage is metered using two balance pools: - **Credit**: Meters standard document conversion, layout analysis, basic generation, translation, and OCR tasks. - **Spark**: Meters heavy computational tasks, such as video compression, reasoning AI generation models, and processing exceptionally large assets. ### Brand DNA A style configuration workspace file that specifies corporate color themes, font groups, layout grids, and background templates. Referenced in Create and Revamp workflows to align design outputs with brand identity guidelines. ### Glossary A terminology mapping profile containing language pairs. Enforced during translation tasks to guarantee consistent nomenclature across translated documents. --- ## [EN] Examples **URL:** `https://app.deckflow.com/docs/en/guide/examples.md` # Examples > An introduction to DeckFlow examples, showcasing typical integration scenarios using the API, MCP, and CLI. This page gathers runnable and copyable code examples, helping you quickly get started with DeckFlow developer tools. All examples are based on the base URL `https://app.deckflow.com/api` and require the `Authorization: Bearer ` header. ## 1. API Integration Examples Submit and poll asynchronous tasks via the HTTP API. The following snippets demonstrate creating a document generation task and polling its status until a download URL is returned. ```javascript const API_KEY = "Bearer "; const BASE_URL = "https://app.deckflow.com/api"; async function generateDeck() { const formData = new FormData(); formData.append("type", "generation"); formData.append("params", JSON.stringify({ inputText: "Generate a market research report on renewable energy trends", pageCount: 10 })); // 1. Submit the task const res = await fetch(`${BASE_URL}/tools/tasks`, { method: "POST", headers: { "Authorization": API_KEY }, body: formData }); const task = await res.json(); console.log("Task submitted. ID:", task.id); // 2. Poll the status const pollInterval = setInterval(async () => { const statusRes = await fetch(`${BASE_URL}/tools/tasks/${task.id}`, { headers: { "Authorization": API_KEY } }); const currentTask = await statusRes.json(); console.log("Task status:", currentTask.status); if (currentTask.status === "completed") { clearInterval(pollInterval); console.log("Success! Download URL:", currentTask.result.url); } else if (currentTask.status === "failed") { clearInterval(pollInterval); console.error("Task failed. Error:", currentTask.error.message); } }, 5000); } generateDeck(); ``` ```python import time import requests API_KEY = "Bearer " BASE_URL = "https://app.deckflow.com/api" def generate_deck(): headers = { "Authorization": API_KEY } data = { "type": "generation", "params": '{"inputText": "Generate a market research report on renewable energy trends", "pageCount": 10}' } # 1. Submit the task response = requests.post(f"{BASE_URL}/tools/tasks", headers=headers, data=data) task = response.json() task_id = task["id"] print(f"Task submitted. ID: {task_id}") # 2. Poll the status while True: status_response = requests.get(f"{BASE_URL}/tools/tasks/{task_id}", headers=headers) current_task = status_response.json() status = current_task["status"] print(f"Task status: {status}") if status == "completed": print(f"Success! Download URL: {current_task['result']['url']}") break elif status == "failed": print(f"Task failed. Error: {current_task['error']['message']}") break time.sleep(5) generate_deck() ``` ## 2. CLI (DeckOps) Automation Examples `DeckOps` is the command-line utility for managing DeckFlow cloud tasks. You can run batch automation from your local terminal or CI/CD pipelines. ### Installation & Configuration ```bash # Clone and link the CLI globally git clone https://github.com/deckflow/deckops.git cd deckops npm install npm link # Set credentials deckops config set-token "Bearer " deckops config set-api-base "https://app.deckflow.com/api" ``` ### Common Commands ```bash # Submit a slide generation task deckops create --params '{"inputText":"AI development in healthcare","pageCount":8}' # Translate a deck and wait for the results deckops translate source_presentation.pptx --from zh --to en --timeout 180 # Compress an archive using the cloud Optimizer deckops compress large_archive.zip ``` ## 3. MCP Agent Integration Examples Configure the DeckFlow MCP server in your AI assistant (e.g. Claude Desktop) to allow LLMs to directly call file optimization, extraction, and generation tools. ### Configuration File Add the following configuration block into your Claude Desktop settings file: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "deckflow": { "command": "node", "args": ["/Users/tong/Downloads/Dev-Docs/heygen-docs/mcp-server/dist/index.js"], "env": { "DECKFLOW_API_KEY": "Bearer " } } } } ``` After saving, restart Claude Desktop to enable the tools inside your chat sessions. --- ## [EN] Limits & Errors **URL:** `https://app.deckflow.com/docs/en/guide/limits-errors.md` # Limits & Errors > DeckFlow limits and error specifications, detailing file size restrictions, task constraints, error responses, and troubleshooting strategies. ## File Size Limits To ensure fair distribution of computing resources and back-end service stability, DeckFlow enforces specific limits on file processing, API request frequency, and quotas. The maximum file size limit supported by each API and tool is listed below. Please ensure that your files do not exceed these thresholds before calling the task creation API: | Feature / Tool Category | Max File Size | Supported Input Formats | | --- | --- | --- | | **Document Translation (Translate)** | **500 MB** | `.pptx`, `.key`, `.pdf`, `.docx`, `.doc`, `.xlsx`, `.xls` | | **HTML Packaging Tool (HTML Player Pack)** | **50 MB** | `.html`, `.htm` | | **HTML Converter (html2png / html2pptx)** | **50 MB** | `.html`, `.htm` (supports pasting HTML code) | | **Markdown Converter (markdown2png)** | **10 MB** | `.md`, `.markdown` (supports pasting Markdown text) | | **Image OCR (image.ocr)** | **50 MB** | `image/*` (e.g., JPG, PNG, etc.) | | **Image Resizing (image.resize)** | **100 MB** | `image/*` (e.g., JPG, PNG, etc.) | | **Image WebP Conversion (image.convertWebp)** | **100 MB** | `image/*` (e.g., JPG, PNG, etc.) | | **Video Compression (video.compress)** | **300 MB** | `video/*` (e.g., MP4, MOV, etc.) | | **Other Document & Presentation Tools** | **300 MB** | `.pptx`, `.ppt`, `.key`, `.docx`, `.doc`, `.xlsx`, `.xls`, `.pdf`, `.zip` | ## API Error Status Codes When an API request fails or task creation errors out, the API returns the corresponding HTTP status code and a JSON response with error details. The following table lists the system-wide status codes: | Status Code | Error Code (`code`) | Description / Scenario | Recommended Troubleshooting & Recovery Solution | | --- | --- | --- | --- | | `400` | `invalid_parameter` | Missing required parameters, invalid parameter format, or unsupported file formats. | Check and correct the `type` or `params` attributes in `POST /tools/tasks`. | | `400` | `file_size_exceeded` | The uploaded file exceeds the maximum file size limit listed above. | Compress the file size or split the presentation into batches before submitting again. | | `401` | `unauthorized` | Missing API key, or the format of the `Authorization` header is incorrect. | Ensure the header format is `Authorization: Bearer `. | | `402` | `insufficient_quota` | Credit or Spark quota within the workspace has been exhausted. | Prompt the user to log in to the DeckFlow settings page to top up or upgrade their plan. | | `403` | `forbidden` | The API key is valid, but lacks permission to access the current workspace, feature, or target Space. | Verify that the `spaceId` parameter is correct and inspect the permissions associated with your API key. | | `429` | `rate_limit_exceeded` | Concurrent API calls have exceeded rate limit thresholds. | Implement client-side Exponential Backoff retries to reduce request concurrency. | | `5xx` | `internal_error` | Internal server error or temporary network issue. | Retry using a backoff strategy. | ## Task Retry Strategy When handling responses from the DeckFlow back-end in your applications, please follow this retry logic: - **Retryable Errors:** HTTP `429` (Rate Limit): Wait and perform an exponential backoff retry. - HTTP `5xx` (Temporary Server Failure): Recommended to automatically retry after a short delay. **Non-Retryable Errors:** - HTTP `400` / `401` / `403`: Typically parameter, authentication, or permission issues. Repeating the request will yield the same result. You must fix the parameters or permissions before retrying. - HTTP `402` (Insufficient Quota): Requires the user to top up or purchase additional quota before retrying. --- ## [EN] Pricing & Billing **URL:** `https://app.deckflow.com/docs/en/guide/pricing-billing.md` # Pricing & Billing > Understand how DeckFlow developer usage consumes Credit and Spark quota. Estimate Tools tasks before running conversions, extraction, compression, and optimization jobs. DeckFlow developer usage is billed against the account or workspace connected to your API key. Tools usage is measured with two quota currencies: `credit` and `spark`. ## How Billing Works Each Tools task can include a fixed base fee and a metered fee. ```text total cost = baseFee + meteredUnits * meterFee.unitPrice ``` If a tool uses both `credit` and `spark`, DeckFlow deducts each currency separately. For example, a compression task can charge `spark` to start the job and `credit` based on file size. > **NOTE** > API key billing: Usage is charged to the account or workspace that owns the API key. Server jobs, MCP calls, CLI runs, and CI automation all consume the same workspace quota when they use the same key. ## Credit and Spark | Unit | Used for | | --- | --- | | `credit` | Standard processing work, including OCR, slide operations, format conversion, image resizing, and most page or text based tools. | | `spark` | Heavier or premium work, including compression and video-oriented processing. Some tools charge Spark only as a base fee, while others meter in Spark too. | ## Metering Units | Meter | Meaning | | --- | --- | | `size_10mb` | File size measured in 10 MB units. | | `text_1k` | Text length measured in 1,000-character units. | | `page_1` | Page or slide count measured one page at a time. | The final charged amount is based on the server-measured file size, text length, or page count. Show an estimate before submitting large jobs, then use the completed task response to display final quota usage. ## Tools Pricing ### Compression | Tool | Base fee | Metered fee | | --- | --- | --- | | `file.compress` | `1 spark` | `2 credit / size_10mb` | | `video.compress` | `1 spark` | `2 credit / size_10mb` | ### Image and OCR | Tool | Base fee | Metered fee | | --- | --- | --- | | `image.ocr` | `1 credit` | `1 credit / page_1` | | `image.convertWebp` | `1 credit` | `2 credit / page_1` | | `image.resize` | `1 credit` | `2 credit / page_1` | ### PPTX Utilities | Tool | Base fee | Metered fee | | --- | --- | --- | | `pptx.split` | `1 credit` | `2 credit / page_1` | | `pptx.join` | `1 credit` | `2 credit / page_1` | | `pptx.getFontInfo` | `1 credit` | `1 credit / page_1` | | `pptx.embedFonts` | `1 spark` | `1 credit / page_1` | ### File Conversion | Tool | Base fee | Metered fee | | --- | --- | --- | | `convertor.ppt2image` | `2 credit` | `2 credit / page_1` | | `convertor.ppt2pptx` | `2 credit` | `2 credit / page_1` | | `convertor.ppt2pdf` | `2 credit` | `2 credit / page_1` | | `convertor.doc2pdf` | `1 credit` | `2 credit / page_1` | | `convertor.ppt2video` | `1 spark` | `1 spark / page_1` | | `convertor.pdf2image` | `1 credit` | `1 credit / page_1` | | `convertor.keynote2image` | `3 credit` | `2 credit / page_1` | | `convertor.keynote2html` | `3 credit` | `2 credit / page_1` | | `convertor.keynote2pdf` | `3 credit` | `2 credit / page_1` | | `convertor.html2pptx` | `3 credit` | `2 credit / page_1` | ### HTML and Markdown Rendering | Tool | Base fee | Metered fee | | --- | --- | --- | | `convertor.html2png` | `1 credit` | `2 credit / text_1k` | | `convertor.markdown2png` | `1 credit` | `2 credit / text_1k` | ## Examples ### Compress a 24 MB file `file.compress` charges `1 spark` plus `2 credit` per 10 MB unit. If the file is billed as 3 size units: ```text 1 spark + (3 * 2 credit) = 1 spark + 6 credit ``` ### Convert a 12-page PPT to PDF `convertor.ppt2pdf` charges `2 credit` plus `2 credit` per page: ```text 2 credit + (12 * 2 credit) = 26 credit ``` ### Convert a 10-slide PPT to video `convertor.ppt2video` charges Spark for both the base fee and page metering: ```text 1 spark + (10 * 1 spark) = 11 spark ``` ## Quota in API Responses Tools responses should include quota usage when a task is accepted or completed. Use these fields to show a clear receipt to your users. ```json { "quota_usage": { "credits_used": 26, "sparks_used": 0, "remaining_credits": 974, "remaining_sparks": 100 } } ``` > **WARNING** > If the workspace does not have enough quota, DeckFlow should reject the job before processing. Do not retry quota errors in a tight loop; ask the user to add quota, change plans, or reduce the task size. --- ## [EN] Quick Start **URL:** `https://app.deckflow.com/docs/en/guide/quick-start.md` # Quick Start > The quick start guide for DeckFlow developers to establish the shortest path for file uploading, task creation, status querying, and result downloading. DeckFlow API utilizes an asynchronous task model for most file operations, supporting multi-language translation, revamp (redesign), and generation of various documents and presentation decks. ## Core Steps ### Step 1: Get & Configure API Key Before getting started, log in to DeckFlow and generate your API Key in the settings page. Configure environment variables to begin using the API: ```bash # Configure API key and base path export DECKFLOW_API_KEY="Bearer " export DECKFLOW_API_BASE="https://app.deckflow.com/api" ``` For more detailed information, see [API Key](./authentication.md). ### Step 2: Submit a Task All task submissions (including generation, translation, revamp, and other tool APIs) are posted to a unified task management endpoint using a single-step `multipart/form-data` format. There is no need to pre-upload files; simply pass your file binary and parameters directly within the request body. - **Request Path**: `POST /tools/tasks` - **Request Headers**: `Authorization`: `Bearer ` - `Content-Type`: `multipart/form-data` **Primary Parameters**: - `files`: Local file binary. - `type`: Task type, e.g. `translation`. - `params`: JSON string parameter configuration, e.g., `{"from":"zh","to":"en"}`. The following snippets demonstrate how to submit a translation task: ```bash curl -X POST "$DECKFLOW_API_BASE/tools/tasks" \ -H "Authorization: $DECKFLOW_API_KEY" \ --form 'files=@"/path/to/presentation.pptx"' \ --form 'type="translation"' \ --form 'params="{\"from\":\"zh\",\"to\":\"en\"}"' ``` ```javascript const formData = new FormData(); formData.append('files', fileInput.files[0]); // Local PPTX/PDF/Word file formData.append('type', 'translation'); formData.append('params', JSON.stringify({ from: 'zh', to: 'en' })); const response = await fetch(`${process.env.DECKFLOW_API_BASE}/tools/tasks`, { method: 'POST', headers: { 'Authorization': process.env.DECKFLOW_API_KEY }, body: formData }); const task = await response.json(); console.log('Created Task:', task); ``` ```python import os, requests url = f"{os.environ['DECKFLOW_API_BASE']}/tools/tasks" headers = { "Authorization": os.environ["DECKFLOW_API_KEY"] } files = [ ("files", ("presentation.pptx", open("presentation.pptx", "rb"), "application/vnd.openxmlformats-officedocument.presentationml.presentation")) ] data = { "type": "translation", "params": '{"from":"zh","to":"en"}' } response = requests.post(url, headers=headers, files=files, data=data) print('Created Task:', response.json()) ``` Once successfully created, the server returns a JSON response containing the `id` (representing `taskId`) with status `pending`. ### Step 3: Get Task Status & Results Since document processing takes some time, you need to use the `taskId` to fetch the progress. DeckFlow supports both **Polling** and **Server-Sent Events (SSE) stream subscription** to retrieve status and results. - **Request Path**: `GET /tools/tasks/{taskId}` #### Method A: Real-time Subscription (SSE) Recommended By specifying the `response-event-stream: yes` header, the server pushes progress events in real-time. The connection will close automatically once the task finishes, saving bandwidth and connection overhead. ```bash curl -X GET "$DECKFLOW_API_BASE/tools/tasks/YOUR_TASK_ID" \ -H "Authorization: $DECKFLOW_API_KEY" \ -H "response-event-stream: yes" ``` ```javascript const url = `${process.env.DECKFLOW_API_BASE}/tools/tasks/${taskId}`; const response = await fetch(url, { headers: { 'Authorization': process.env.DECKFLOW_API_KEY, 'response-event-stream': 'yes' } }); const reader = response.body.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const chunk = decoder.decode(value); const lines = chunk.split('\n'); for (const line of lines) { if (line.startsWith('data:')) { const taskJSON = JSON.parse(line.replace('data:', '').trim()); console.log('Received push status:', taskJSON.status); if (taskJSON.status === 'completed' || taskJSON.status === 'failed') { console.log('Final Result:', taskJSON); return; } } } } ``` ```python import os, requests, json url = f"{os.environ['DECKFLOW_API_BASE']}/tools/tasks/{task_id}" headers = { "Authorization": os.environ["DECKFLOW_API_KEY"], "response-event-stream": "yes" } response = requests.get(url, headers=headers, stream=True) for line in response.iter_lines(): if line: decoded_line = line.decode('utf-8') if decoded_line.startswith('data:'): task_json = json.loads(decoded_line.replace('data:', '').strip()) print("Received push status:", task_json.get("status")) if task_json.get("status") in ["completed", "failed"]: print("Final Result:", task_json) break ``` #### Method B: Periodic Polling The client sends requests periodically (e.g. every 3-5 seconds) to check status until the task enters a terminal state (`completed` or `failed`). ```bash curl -X GET "$DECKFLOW_API_BASE/tools/tasks/YOUR_TASK_ID" \ -H "Authorization: $DECKFLOW_API_KEY" ``` ```javascript async function pollTask(taskId) { const url = `${process.env.DECKFLOW_API_BASE}/tools/tasks/${taskId}`; const headers = { 'Authorization': process.env.DECKFLOW_API_KEY }; while (true) { const res = await fetch(url, { headers }); const task = await res.json(); console.log('Current status:', task.status); if (task.status === 'completed') { console.log('Success! Download URL:', task.result.url); break; } else if (task.status === 'failed') { console.error('Failed! Error:', task.error); break; } await new Promise(resolve => setTimeout(resolve, 3000)); } } ``` ```python import os, requests, time def poll_task(task_id): url = f"{os.environ['DECKFLOW_API_BASE']}/tools/tasks/{task_id}" headers = { "Authorization": os.environ["DECKFLOW_API_KEY"] } while True: response = requests.get(url, headers=headers) task = response.json() status = task.get("status") print("Current status:", status) if status == "completed": print("Success! Download URL:", task["result"]["url"]) break elif status == "failed": print("Failed! Error:", task.get("error")) break time.sleep(3) ``` ### Step 4: Download Results Once the status becomes `completed`, retrieve the temporarily signed download URL from `result.url` and save the output file locally. > **NOTE** > Temporarily signed URLs have a limited expiration time. To preserve your processed files permanently, please download and save them to your own storage servers or databases before the link expires. --- ## [EN] Webhooks / Async Jobs **URL:** `https://app.deckflow.com/docs/en/guide/webhooks-async-jobs.md` # Webhooks / Async Jobs > Understanding DeckFlow's asynchronous execution model, status polling, and Webhook callbacks for long-running file processing tasks. Most document processing operations in DeckFlow—such as generation, translation, revamp, and format conversion—are computationally intensive. To ensure immediate API responses, DeckFlow utilizes an asynchronous task execution model. After submitting a task (`POST /tools/tasks`), developers can retrieve the final results using three different methods: **SSE Real-time Subscription (Server-Sent Events)**, **API Polling (Polling)**, and **Webhook Callbacks (Webhook Callback)**. ## 1. Comparison of Status Retrieval Methods To help you choose the best integration pattern, the following table compares the advantages and disadvantages of SSE real-time stream subscription and periodic polling: | Method | Recommendation | Pros | Cons | Ideal Use Cases | | --- | --- | --- | --- | --- | | **SSE Real-time Subscription (Server-Sent Events)** | **Recommended (Highly Recommended)** | Extremely real-time; lightweight and resource-efficient (single HTTP connection); no need for repeated connection establishment; server pushes updates automatically. | Requires client support for stream response parsing; developers need to implement reconnect logic for network disruptions. | Web/client applications, CLI automation scripts, and front-end interfaces requiring live progress feedback. | | **API Periodic Polling (Polling)** | **Backup / Fallback Only** | Simple to implement; natively supported by all HTTP clients; no streaming requirements on the client environment. | Higher latency; repeated requests consume substantial network bandwidth and server resources, making it prone to triggering `429` rate limits. | Simple backend background jobs, or restricted environments where long-lived connections cannot be maintained. | ## 2. Server-Sent Events (SSE) Real-time Subscription When a client queries the task status, sending a specific HTTP header will instruct the DeckFlow server to upgrade the connection to an SSE real-time data stream. ### API Specification - **Request Path**: `GET /tools/tasks/{taskId}` - **Required Header**: `response-event-stream: yes` (must be set to `yes` to enable SSE mode) ### Code Examples ```bash # Retrieve live progress updates via curl curl -X GET "https://app.deckflow.com/api/tools/tasks/YOUR_TASK_ID" \ -H "Authorization: Bearer " \ -H "response-event-stream: yes" ``` ```javascript const taskId = "YOUR_TASK_ID"; const url = `https://app.deckflow.com/api/tools/tasks/${taskId}`; async function subscribeTaskSSE() { const response = await fetch(url, { headers: { 'Authorization': 'Bearer ', 'response-event-stream': 'yes' } }); const reader = response.body.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const chunk = decoder.decode(value); const lines = chunk.split('\n'); for (const line of lines) { if (line.startsWith('data:')) { const task = JSON.parse(line.replace('data:', '').trim()); console.log('Received progress update:', task.status); if (task.status === 'completed') { console.log('Task completed! Download URL:', task.result.url); return; } else if (task.status === 'failed') { console.error('Task failed. Error details:', task.error); return; } } } } } subscribeTaskSSE(); ``` ```python import requests, json task_id = "YOUR_TASK_ID" url = f"https://app.deckflow.com/api/tools/tasks/{task_id}" headers = { "Authorization": "Bearer ", "response-event-stream": "yes" } def subscribe_task_sse(): response = requests.get(url, headers=headers, stream=True) for line in response.iter_lines(): if line: decoded_line = line.decode('utf-8') if decoded_line.startswith('data:'): task = json.loads(decoded_line.replace('data:', '').strip()) print("Received progress update:", task.get("status")) if task.get("status") == "completed": print("Task completed! Download URL:", task["result"]["url"]) break elif task.get("status") == "failed": print("Task failed. Error details:", task.get("error")) break subscribe_task_sse() ``` ## 3. API Periodic Polling (Polling) When using the polling pattern, the client submits multiple separate HTTP requests to the task status endpoint. ### API Specification - **Request Path**: `GET /tools/tasks/{taskId}` - **Required Header**: `Authorization: Bearer ` ### Polling Guidelines 1. **Exponential Backoff**: Start with an initial interval of about 3 seconds. Gradually increase the delay between attempts (e.g., 3s -> 5s -> 10s -> 20s) as time passes to avoid rate limits (`429 Rate Limit`). 2. **Hard Timeout boundaries**: Establish a maximum polling duration (such as 5 minutes). If the task does not finish within this duration, terminate the polling and handle the timeout. ### Code Examples ```javascript const taskId = "YOUR_TASK_ID"; const url = `https://app.deckflow.com/api/tools/tasks/${taskId}`; const headers = { 'Authorization': 'Bearer ' }; async function pollTaskStatus() { let delay = 3000; // Start with a 3-second delay const maxDelay = 30000; // Cap delay at 30 seconds while (true) { const res = await fetch(url, { headers }); const task = await res.json(); console.log('Polling status:', task.status); if (task.status === 'completed') { console.log('Task succeeded. Download URL:', task.result.url); break; } else if (task.status === 'failed') { console.error('Task failed. Reason:', task.error); break; } // Exponential backoff wait await new Promise(resolve => setTimeout(resolve, delay)); delay = Math.min(delay * 1.5, maxDelay); } } pollTaskStatus(); ``` ```python import requests, time task_id = "YOUR_TASK_ID" url = f"https://app.deckflow.com/api/tools/tasks/{task_id}" headers = { "Authorization": "Bearer " } def poll_task_status(): delay = 3.0 # Start with 3 seconds max_delay = 30.0 while True: response = requests.get(url, headers=headers) task = response.json() status = task.get("status") print("Polling status:", status) if status == "completed": print("Task succeeded. Download URL:", task["result"]["url"]) break elif status == "failed": print("Task failed. Reason:", task.get("error")) break time.sleep(delay) delay = min(delay * 1.5, max_delay) poll_task_status() ``` ## 4. Webhook Callbacks For integrations that prefer to avoid active polling or streaming (such as background offline batch jobs), DeckFlow can push the final task status to your server using Webhook callbacks. ### Configuration Submit the task (`POST /tools/tasks`) with a `notifyURL` parameter in the Form Data body, containing the publicly reachable HTTP URL of your listener endpoint. ### Payload & Lifecycle When the task reaches its final state (`completed` or `failed`), DeckFlow will dispatch an HTTP `POST` request to your `notifyURL`. - **Payload Format**: `application/json` - **Payload Structure**: The complete Task entity JSON object. #### Callback Body Example: ```json { "id": "task-550e8400-e29b-41d4-a716-446655440000", "name": "Market Research Slide Revamp", "type": "revamp", "status": "completed", "result": { "url": "https://app.deckflow.com/download/processed-presentation.pptx?...", "mimeType": "application/vnd.openxmlformats-officedocument.presentationml.presentation" }, "createdAt": "2026-06-11T08:52:00.000Z", "updatedAt": "2026-06-11T08:54:15.000Z" } ``` --- ## [EN] Create Task (Generation) **URL:** `https://app.deckflow.com/docs/en/api/create.md` # Create Task (Generation) > Generate professional presentation slides (PPTX) using complex documents, text prompts, or URLs. **HTTP Method:** `POST` **Endpoint:** `/tools/tasks` ## Interface Specification Create an asynchronous slide generation task. The value for `type` must be `generation`. POST `/tools/tasks` Try it ### Request Headers | Header | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `String` | Yes | `Bearer ` — Your developer API key. | | `Content-Type` | `String` | Yes | Must be `multipart/form-data`. | ### POST Request Body Parameters (Form Data) | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `spaceId` | `String` | No | Target workspace Space ID. | | `files` | `File` | No | Reference document files (PDF, Word, or Markdown). Supports multiple files. | | `type` | `String` | Yes | Task type. Fixed value: `generation`. | | `name` | `String` | No | Task display name, e.g., `"AI Document Generation Task"`. | | `params` | `String (JSON)` | Yes | JSON string containing task parameters. Detailed fields below. | ## Task Parameters (params) Inner properties supported inside the `params` JSON string: | Field | Type | Required | Description | | --- | --- | --- | --- | | `inputText` | `String` | No | Topic description, webpage URL, or raw text to build slide structures. | | `enableSearch` | `Boolean` | No | Enable web search to research and enrich content details. Default: `false`. | | `advancedModel` | `Boolean` | No | Use reasoning AI models for better logic and creative slides. Default: `false`. | | `fastMode` | `Boolean` | No | Prioritize faster execution speed over layout optimizations. Default: `false`. | | `intent` | `String` | No | Custom goal context or intention. | | `audience` | `String` | No | Target audience details to guide layouts and copywriting style. | | `pageCount` | `Integer` | No | Target number of slides to generate. | | `author` | `String` | No | PPTX author metadata. | | `notifyURL` | `String` | No | Webhook callback address triggered on task status changes. | ### Request Examples #### cURL Request Example ```bash curl --location 'https://app.deckflow.com/api/tools/tasks' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'spaceId="space-default"' \ --form 'files=@"/path/to/presentation.pptx"' \ --form 'type="generation"' \ --form 'name="AI Document Generation Task"' \ --form 'params="{\"inputText\":\"Write an analysis report on the development trends of the renewable energy industry, highlighting the market shares of solar and wind energy.\",\"enableSearch\":true,\"advancedModel\":false,\"fastMode\":false,\"pageCount\":10}"' ``` #### JavaScript Request Example ```javascript const formData = new FormData(); formData.append('spaceId', 'space-default'); formData.append('files', fileInput.files[0]); // presentation.pptx formData.append('type', 'generation'); formData.append('name', 'AI Document Generation Task'); formData.append('params', '{"inputText":"Write an analysis report on the development trends of the renewable energy industry, highlighting the market shares of solar and wind energy.","enableSearch":true,"advancedModel":false,"fastMode":false,"pageCount":10}'); fetch('https://app.deckflow.com/api/tools/tasks', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' }, body: formData }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python 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/octet-stream")) ] data = { "spaceId": "space-default", "type": "generation", "name": "AI Document Generation Task", "params": '{"inputText":"Write an analysis report on the development trends of the renewable energy industry, highlighting the market shares of solar and wind energy.","enableSearch":true,"advancedModel":false,"fastMode":false,"pageCount":10}' } response = requests.post(url, headers=headers, files=files, data=data) print(response.json()) ``` ### Response Examples #### Response 200 ```json {{ "id": "task-uuid-string", "spaceId": "space-default", "name": "AI Document Generation Task", "type": "generation", "status": "pending", "preview": null, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:00.000Z" }} ``` #### Response 400 ```json {{ "error": {{ "code": "invalid_parameter", "message": "type and params are required parameters." }} }} ``` #### Response 401 ```json {{ "error": {{ "code": "unauthorized", "message": "Invalid API Key or authorization header." }} }} ``` --- ## [EN] Query Generation Task **URL:** `https://app.deckflow.com/docs/en/api/get-generation-task.md` # Query Generation Task > Query the execution progress and download URL of a document generation task. **HTTP Method:** `GET` **Endpoint:** `/tools/tasks/:id` ## Interface Specification Query generation task execution progress and get the download details from `result.url` once complete. GET `/tools/tasks/:id` Try it ### Request Headers | Header | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `String` | Yes | `Bearer ` — Your developer API key. | ### Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `id` | `String` | Yes | The task ID returned when submitting the generation task. | ### Request Examples #### cURL Request Example ```bash curl -X GET "https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC" \ -H "Authorization: Bearer YOUR_API_KEY" ``` #### JavaScript Request Example ```javascript fetch('https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python import requests url = "https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC" headers = { "Authorization": "Bearer YOUR_API_KEY" } response = requests.get(url, headers=headers) print(response.json()) ``` ### Response Examples #### Response 200 ```json {{ "id": "Pt1AtI67yauC", "spaceId": "space-default", "type": "generation", "status": "success", "error": null, "progress": 100, "params": {{ "inputText": "Write an analysis report on the development trends of the renewable energy industry, highlighting the market shares of solar and wind energy.", "enableSearch": true, "pageCount": 10 }}, "result": {{ "url": "https://app.deckflow.com/api/tasks/Pt1AtI67yauC/download", "format": "pptx", "sizeBytes": 2048576 }}, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:15.000Z" }} ``` #### Response 400 ```json {{ "error": {{ "code": "invalid_parameter", "message": "The request parameters are invalid or missing." }} }} ``` #### Response 401 ```json {{ "error": {{ "code": "unauthorized", "message": "Invalid API Key or authorization header." }} }} ``` #### Response 429 ```json {{ "error": {{ "code": "rate_limit_exceeded", "message": "Too many requests. Please slow down and try again later." }} }} ``` --- ## [EN] Query Revamp Task **URL:** `https://app.deckflow.com/docs/en/api/get-revamp-task.md` # Query Revamp Task > Query the execution progress and download URL of a document revamp task. **HTTP Method:** `GET` **Endpoint:** `/tools/tasks/:id` ## Interface Specification Query revamp task execution progress and get the download details from `result.url` once complete. GET `/tools/tasks/:id` Try it ### Request Headers | Header | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `String` | Yes | `Bearer ` — Your developer API key. | ### Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `id` | `String` | Yes | The task ID returned when submitting the revamp task. | ### Request Examples #### cURL Request Example ```bash curl -X GET "https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC" \ -H "Authorization: Bearer YOUR_API_KEY" ``` #### JavaScript Request Example ```javascript fetch('https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python import requests url = "https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC" headers = { "Authorization": "Bearer YOUR_API_KEY" } response = requests.get(url, headers=headers) print(response.json()) ``` ### Response Examples #### Response 200 ```json {{ "id": "Pt1AtI67yauC", "spaceId": "space-default", "type": "revamp", "status": "success", "error": null, "progress": 100, "params": {{ "inputText": "Change font to Outfit and use green/blue palette" }}, "result": {{ "url": "https://app.deckflow.com/api/tasks/Pt1AtI67yauC/download", "format": "pptx", "sizeBytes": 2205120 }}, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:25.000Z" }} ``` #### Response 400 ```json {{ "error": {{ "code": "invalid_parameter", "message": "The request parameters are invalid or missing." }} }} ``` #### Response 401 ```json {{ "error": {{ "code": "unauthorized", "message": "Invalid API Key or authorization header." }} }} ``` #### Response 429 ```json {{ "error": {{ "code": "rate_limit_exceeded", "message": "Too many requests. Please slow down and try again later." }} }} ``` --- ## [EN] Query Translation Task **URL:** `https://app.deckflow.com/docs/en/api/get-translation-task.md` # Query Translation Task > Query the execution progress and download URL of a document translation task. **HTTP Method:** `GET` **Endpoint:** `/tools/tasks/:id` ## Interface Specification Query translation task execution progress and get the download details from `result.url` once complete. GET `/tools/tasks/:id` Try it ### Request Headers | Header | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `String` | Yes | `Bearer ` — Your developer API key. | ### Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `id` | `String` | Yes | The task ID returned when submitting the translation task. | ### Request Examples #### cURL Request Example ```bash curl -X GET "https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC" \ -H "Authorization: Bearer YOUR_API_KEY" ``` #### JavaScript Request Example ```javascript fetch('https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python import requests url = "https://app.deckflow.com/api/tools/tasks/Pt1AtI67yauC" headers = { "Authorization": "Bearer YOUR_API_KEY" } response = requests.get(url, headers=headers) print(response.json()) ``` ### Response Examples #### Response 200 ```json {{ "id": "Pt1AtI67yauC", "spaceId": "space-default", "type": "translation", "status": "success", "error": null, "progress": 100, "params": {{ "from": "zh", "to": "en" }}, "result": {{ "url": "https://app.deckflow.com/api/tasks/Pt1AtI67yauC/download", "format": "pptx", "sizeBytes": 1845120 }}, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:20.000Z" }} ``` #### Response 400 ```json {{ "error": {{ "code": "invalid_parameter", "message": "The request parameters are invalid or missing." }} }} ``` #### Response 401 ```json {{ "error": {{ "code": "unauthorized", "message": "Invalid API Key or authorization header." }} }} ``` #### Response 429 ```json {{ "error": {{ "code": "rate_limit_exceeded", "message": "Too many requests. Please slow down and try again later." }} }} ``` --- ## [EN] Submit Revamp Task **URL:** `https://app.deckflow.com/docs/en/api/revamp.md` # Submit Revamp Task > Upgrade presentation layouts, colors, and Brand DNA while preserving the original slide content. **HTTP Method:** `POST` **Endpoint:** `/tools/tasks` ## Interface Specification Create an asynchronous slide revamp task. The value for `type` must be `revamp`. POST `/tools/tasks` Try it ### Request Headers | Header | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `String` | Yes | `Bearer ` — Your developer API key. | | `Content-Type` | `String` | Yes | Must be `multipart/form-data`. | ### POST Request Body Parameters (Form Data) | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `spaceId` | `String` | No | Target workspace Space ID. | | `files` | `File` | Yes | The presentation files to revamp (PPTX). Supports multiple files. | | `type` | `String` | Yes | Task type. Fixed value: `revamp`. | | `name` | `String` | No | Task display name, e.g., `"AI Document Revamp Task"`. | | `params` | `String (JSON)` | Yes | JSON string containing task parameters. Detailed fields below. | ## Task Parameters (params) Inner properties supported inside the `params` JSON string: | Field | Type | Required | Description | | --- | --- | --- | --- | | `inputText` | `String` | No | Style instructions, color rules, or theme DNA descriptions to guide the revamp. | | `advancedModel` | `Boolean` | No | Use advanced design reasoning AI. Default: `false`. | | `fastMode` | `Boolean` | No | Prioritize faster execution speed. Default: `false`. | | `notifyURL` | `String` | No | Webhook callback address triggered on task status changes. | ### Request Examples #### cURL Request Example ```bash curl --location 'https://app.deckflow.com/api/tools/tasks' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'spaceId="space-default"' \ --form 'files=@"/path/to/presentation.pptx"' \ --form 'type="revamp"' \ --form 'name="AI Document Revamp Task"' \ --form 'params="{\"inputText\":\"Change font to Outfit and use green/blue palette\",\"advancedModel\":false,\"fastMode\":false}"' ``` #### JavaScript Request Example ```javascript const formData = new FormData(); formData.append('spaceId', 'space-default'); formData.append('files', fileInput.files[0]); // presentation.pptx formData.append('type', 'revamp'); formData.append('name', 'AI Document Revamp Task'); formData.append('params', '{"inputText":"Change font to Outfit and use green/blue palette","advancedModel":false,"fastMode":false}'); fetch('https://app.deckflow.com/api/tools/tasks', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' }, body: formData }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python 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/octet-stream")) ] data = { "spaceId": "space-default", "type": "revamp", "name": "AI Document Revamp Task", "params": '{"inputText":"Change font to Outfit and use green/blue palette","advancedModel":false,"fastMode":false}' } response = requests.post(url, headers=headers, files=files, data=data) print(response.json()) ``` ### Response Examples #### Response 200 ```json {{ "id": "task-uuid-string", "spaceId": "space-default", "name": "AI Document Revamp Task", "type": "revamp", "status": "pending", "preview": null, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:00.000Z" }} ``` #### Response 400 ```json {{ "error": {{ "code": "invalid_parameter", "message": "type and params are required parameters." }} }} ``` #### Response 401 ```json {{ "error": {{ "code": "unauthorized", "message": "Invalid API Key or authorization header." }} }} ``` --- ## [EN] File Converter **URL:** `https://app.deckflow.com/docs/en/api/tools-converter.md` # File Converter > The File Converter API specifications and task parameters, supporting conversion between HTML, Image, Keynote, Markdown, PDF, PPT/PPTX, Word, and other formats. **HTTP Method:** `POST` **Endpoint:** `/tools/tasks` ## API Endpoints File conversion tasks are processed asynchronously. Use the two endpoints below to create and retrieve tasks. Click "Try it" on the right to open the interactive playground. POST `/tools/tasks` Try it Creates an asynchronous conversion task. Pass the corresponding converter tool identifier in `type`. GET `/tools/tasks/:id` Try it Queries the execution status of a conversion task and retrieves the final output download link via `result.url`. ### Request Headers | Header | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `String` | Yes | `Bearer ` — API Key. | | `Content-Type` | `String` | Yes (POST) | Must be `multipart/form-data`. | ### POST Body Parameters (Form Data) | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `files` | `File` | Yes | Source file to be processed. Supports uploading multiple files. | | `type` | `String` | Yes | Task type identifier. For example: `convertor.ppt2pdf`. | | `params` | `String (JSON)` | No | JSON string of tool-specific parameters. Defaults to an empty JSON string `"{}"`. | | `notifyURL` | `String` | No | Webhook callback URL to receive task status update notifications. | ## Task Parameter Specifications The specific task types, format requirements, file size limits, and custom parameters (`params`) for each File Converter tool are detailed below: | Tool Name (UI Display) | Tool ID | Backend Task Type (`type`) | Accepted Extensions (`accept`) | File Size Limit | Special Parameters (`params`) | | --- | --- | --- | --- | --- | --- | | **HTML to PNG** | `html2png` | `convertor.html2png` | `.html`, `.htm` | 50 MB | `{}` *Supports directly pasting HTML code as file input* | | **HTML to PPTX** | `html2pptx` | `convertor.html2pptx` | `.html`, `.htm` | 50 MB | `{"needEmbedFonts": boolean}` *Whether to embed fonts in the generated PPTX. Supports pasting HTML* | | **Image to WebP** | `image-convert-webp` | `image.convertWebp` | `image/*` | 100 MB | `{}` | | **Keynote to HTML** | `keynote2html` | `convertor.keynote2html` | `.key` | 300 MB | `{}` | | **Keynote to Image** | `keynote2image` | `convertor.keynote2image` | `.key` | 300 MB | `{}` | | **Keynote to PDF** | `keynote2pdf` | `convertor.keynote2pdf` | `.key` | 300 MB | `{}` | | **Markdown to Image** | `markdown2png` | `convertor.markdown2png` | `.md`, `.markdown` | 10 MB | `{}` *Supports directly pasting Markdown text as file input* | | **PDF to Image** | `pdf2image` | `convertor.pdf2image` | `.pdf` | 300 MB | `{}` | | **PPT to PPTX** | `ppt2pptx` | `convertor.ppt2pptx` | `.ppt` | 300 MB | `{}` | | **PowerPoint to PDF** | `ppt2pdf` | `convertor.ppt2pdf` | `.ppt`, `.pptx` | 300 MB | `{}` | | **PowerPoint to Image** | `ppt2image` | `convertor.ppt2image` | `.ppt`, `.pptx` | 300 MB | `{}` | | **PowerPoint to Video** | `ppt2video` | `convertor.ppt2video` | `.ppt`, `.pptx` | 300 MB | `{}` | | **Word to PDF** | `doc2pdf` | `convertor.doc2pdf` | `.doc`, `.docx` | 300 MB | `{}` | ### Request Examples #### cURL Request Example ```bash curl --location 'https://app.deckflow.com/api/tools/tasks' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'files=@"presentation.pptx"' \ --form 'type="convertor.ppt2pdf"' \ --form 'params="{}"' ``` #### JavaScript Request Example ```javascript const formData = new FormData(); formData.append('files', fileInput.files[0]); formData.append('type', 'convertor.ppt2pdf'); formData.append('params', '{}'); fetch('https://app.deckflow.com/api/tools/tasks', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' }, body: formData }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python 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/octet-stream")) ] data = { "type": "convertor.ppt2pdf", "params": "{}" } response = requests.post(url, headers=headers, files=files, data=data) print(response.json()) ``` ### Response Examples #### Response 200 ```json { "id": "task-uuid-string", "spaceId": "space-default", "name": "presentation.pptx", "type": "convertor.ppt2pdf", "status": "pending", "preview": null, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:00.000Z" } ``` #### Response 400 ```json { "error": { "code": "invalid_parameter", "message": "files and type are required parameters." } } ``` #### Response 401 ```json { "error": { "code": "unauthorized", "message": "Invalid API Key or authorization header." } } ``` --- ## [EN] Extractor **URL:** `https://app.deckflow.com/docs/en/api/tools-extractor.md` # Extractor > The Extractor API specifications and task parameters, supporting optical character recognition (OCR) from images or font detection and text extraction from PPTX presentations. **HTTP Method:** `POST` **Endpoint:** `/tools/tasks` ## API Endpoints File extraction tasks are processed asynchronously. Use the two endpoints below to create and retrieve tasks. Click "Try it" on the right to open the interactive playground. POST `/tools/tasks` Try it Creates an asynchronous extraction task. Pass the corresponding extractor tool identifier in `type`. GET `/tools/tasks/:id` Try it Queries the execution status of an extraction task and retrieves the final output download link via `result.url`. ### Request Headers | Header | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `String` | Yes | `Bearer ` — API Key. | | `Content-Type` | `String` | Yes (POST) | Must be `multipart/form-data`. | ### POST Request Body Parameters (Form Data) | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `files` | `File` | Yes | The source file to be processed. Supports uploading multiple files. | | `type` | `String` | Yes | Task type identifier. For example: `image.ocr`. | | `params` | `String (JSON)` | No | JSON string of tool-specific parameters. Defaults to empty JSON string `"{}"`. | | `notifyURL` | `String` | No | Webhook callback URL to receive task status update notifications. | ## Task Parameter Specifications ### Image OCR Extracts multilingual text from images. Supports `image/*` format, with a file size limit of 50 MB. The structure of `params` is as follows: ```json { "language": "zh-hans" // string. Recognition language. Options: "zh-hans" (Simplified Chinese) | "zh-hant" (Traditional Chinese) | "en" (English) | "ja" (Japanese) | "ko" (Korean) | "fr" (French) | "de" (German) | "es" (Spanish) } ``` ### PPTX Font Finder Scans and lists all font families referenced in a presentation slides. Supports `.pptx` format, with a file size limit of 300 MB. `params` is an empty object `{}`. ### PPTX Text Extractor Extracts text shapes from all slide layers, supporting custom structural filtering. Supports `.pptx` format, with a file size limit of 300 MB. The structure of `params` is as follows: ```json { "hasChildren": false, // boolean. Whether to include child layers (recursively extract text from child shapes) "pickPages": [1, 2, 5], // array. Optional. List of slide page numbers to extract (1-based index) "imageFilter": 0.2, // number. Optional. Filter elements based on area ratio relative to slide (0~1) "includeLayout": false, // boolean. Whether to extract text from layout slides "includeMaster": false, // boolean. Whether to extract text from master slides "includeNotes": false, // boolean. Whether to extract text from notes slides "ignoreEmptyText": true, // boolean. Whether to filter out empty text boxes "onlyBrief": true // boolean. Whether to return a simplified summary structure (reduces payload size) } ``` ### Request Examples #### cURL Request Example ```bash curl --location 'https://app.deckflow.com/api/tools/tasks' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'files=@"presentation.png"' \ --form 'type="image.ocr"' \ --form 'params="{\"language\":\"zh-hans\"}"' ``` #### JavaScript Request Example ```javascript const formData = new FormData(); formData.append('files', fileInput.files[0]); formData.append('type', 'image.ocr'); formData.append('params', '{"language":"zh-hans"}'); fetch('https://app.deckflow.com/api/tools/tasks', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' }, body: formData }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python import requests url = "https://app.deckflow.com/api/tools/tasks" headers = { "Authorization": "Bearer YOUR_API_KEY" } files = [ ("files", ("presentation.png", open("presentation.png", "rb"), "image/png")) ] data = { "type": "image.ocr", "params": '{"language":"zh-hans"}' } response = requests.post(url, headers=headers, files=files, data=data) print(response.json()) ``` ### Response Examples #### Response 200 ```json { "id": "task-uuid-string", "spaceId": "space-default", "name": "image.png", "type": "image.ocr", "status": "pending", "preview": null, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:00.000Z" } ``` #### Response 400 ```json { "error": { "code": "invalid_parameter", "message": "files and type are required parameters." } } ``` #### Response 401 ```json { "error": { "code": "unauthorized", "message": "Invalid API Key or authorization header." } } ``` --- ## [EN] Merger & Splitter **URL:** `https://app.deckflow.com/docs/en/api/tools-merger-splitter.md` # Merger & Splitter > The Merger & Splitter API specifications and task parameters, supporting merging multiple PPTX files, packing HTML pages into a standalone player, or splitting PPTX presentations. **HTTP Method:** `POST` **Endpoint:** `/tools/tasks` ## API Endpoints Merging and splitting tasks are processed asynchronously. Use the two endpoints below to create and retrieve tasks. Click "Try it" on the right to open the interactive playground. POST `/tools/tasks` Try it Creates an asynchronous merge or split task. Pass the corresponding merger/splitter tool identifier in `type`. GET `/tools/tasks/:id` Try it Queries the execution status of a merge/split task and retrieves the final output download link via `result.url`. ### Request Headers | Header | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `String` | Yes | `Bearer ` — API Key. | | `Content-Type` | `String` | Yes (POST) | Must be `multipart/form-data`. | ### POST Request Body Parameters (Form Data) | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `files` | `File` | Yes | The source files to be processed. Supports uploading multiple files. `pptx.join` requires at least 2 files. | | `type` | `String` | Yes | Task type identifier. For example: `pptx.join`. | | `params` | `String (JSON)` | No | JSON string of tool-specific parameters. Defaults to empty JSON string `"{}"`. | | `notifyURL` | `String` | No | Webhook callback URL to receive task status update notifications. | ## Task Parameter Specifications ### PPTX Merger Merges multiple PPTX files sequentially into a single presentation. Supports `.pptx` format, with a file size limit of 300 MB per file. The order of file uploads determines the sequence of merged slides. `params` is an empty object `{}`. ### HTML Player Pack Packages multiple independent HTML slides into a unified, visually appealing web player environment with built-in navigation controls. Supports `.html` and `.htm` formats, with a file size limit of 50 MB per file. The structure of `params` is as follows: ```json { "contents": [{}, {}], // array of objects. Required. The length and order must match the uploaded files sequence "pageWidth": 1280, // number. Player canvas width resolution (pixels) "pageHeight": 720, // number. Player canvas height resolution (pixels) "title": "Presentation", // string. Main presentation title shown in player "description": "Details", // string. Subtitle or brief description shown in player "brandMarkPosition": "none" // string. Position of the brand logo, defaults to "none" } ``` ### PPTX Splitter Splits a multi-slide PPTX file into individual, single-slide PPTX presentations. Supports `.pptx` format, with a file size limit of 300 MB. `params` is an empty object `{}` (the output will be a ZIP archive containing all split single-page PPTX files upon completion). ### Request Examples #### cURL Request Example ```bash curl --location 'https://app.deckflow.com/api/tools/tasks' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'files=@"presentation1.pptx"' \ --form 'files=@"presentation2.pptx"' \ --form 'type="pptx.join"' \ --form 'params="{}"' ``` #### JavaScript Request Example ```javascript const formData = new FormData(); // Add all files to the form formData.append('files', fileInput.files[0]); // presentation1.pptx formData.append('files', fileInput.files[1]); // presentation2.pptx formData.append('type', 'pptx.join'); formData.append('params', '{}'); fetch('https://app.deckflow.com/api/tools/tasks', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' }, body: formData }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python import requests url = "https://app.deckflow.com/api/tools/tasks" headers = { "Authorization": "Bearer YOUR_API_KEY" } files = [ ("files", ("presentation1.pptx", open("presentation1.pptx", "rb"), "application/octet-stream")), ("files", ("presentation2.pptx", open("presentation2.pptx", "rb"), "application/octet-stream")) ] data = { "type": "pptx.join", "params": "{}" } response = requests.post(url, headers=headers, files=files, data=data) print(response.json()) ``` ### Response Examples #### Response 200 ```json { "id": "task-uuid-string", "spaceId": "space-default", "name": "joined-presentation.pptx", "type": "pptx.join", "status": "pending", "preview": null, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:00.000Z" } ``` #### Response 400 ```json { "error": { "code": "invalid_parameter", "message": "files and type are required parameters." } } ``` #### Response 401 ```json { "error": { "code": "unauthorized", "message": "Invalid API Key or authorization header." } } ``` --- ## [EN] Optimizer **URL:** `https://app.deckflow.com/docs/en/api/tools-optimizer.md` # Optimizer > The Optimizer API specifications and task parameters, supporting file compression, image resizing, PPTX font embedding, and video size reduction. **HTTP Method:** `POST` **Endpoint:** `/tools/tasks` ## API Endpoints Optimization tasks are processed asynchronously. Use the two endpoints below to create and retrieve tasks. Click "Try it" on the right to open the interactive playground. POST `/tools/tasks` Try it Creates an asynchronous optimization task. Pass the corresponding optimizer tool identifier in `type`. GET `/tools/tasks/:id` Try it Queries the execution status of an optimization task and retrieves the final output download link via `result.url`. ### Request Headers | Header | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `String` | Yes | `Bearer ` — API Key. | | `Content-Type` | `String` | Yes (POST) | Must be `multipart/form-data`. | ### POST Request Body Parameters (Form Data) | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `files` | `File` | Yes | The source file to be processed. Supports uploading multiple files. | | `type` | `String` | Yes | Task type identifier. For example: `file.compress`. | | `params` | `String (JSON)` | No | JSON string of tool-specific parameters. Defaults to empty JSON string `"{}"`. | | `notifyURL` | `String` | No | Webhook callback URL to receive task status update notifications. | ## Task Parameter Specifications ### File Compressor Reduces the file size of office documents and archives while maximizing visual quality. Supports `.zip`, `.pptx`, `.key`, `.docx`, `.xlsx` formats, with a file size limit of 300 MB. `params` is an empty object `{}`. ### Image Resizer Customizable resizing of images while maintaining original aspect ratio. Supports `image/*` format, with a file size limit of 100 MB. The structure of `params` is as follows: ```json { "maxWidth": 800, // number. Optional. Restricts max width in pixels (mutually exclusive with maxHeight) "maxHeight": 600 // number. Optional. Restricts max height in pixels (mutually exclusive with maxWidth) } ``` ### PPTX Font Embedder Embeds external fonts directly into PPTX presentations to resolve formatting discrepancies due to missing system fonts. Supports `.pptx` format, with a file size limit of 300 MB. The structure of `params` is as follows: ```json { "usedFonts": ["Inter", "Roboto"] // array of strings. Array of font family names to embed from Google Fonts library } ``` ### Video Size Reducer Compresses video file size efficiently to reduce bandwidth usage. Supports `video/*` (e.g. MP4, MOV, and other common formats), with a file size limit of 300 MB. `params` is an empty object `{}`. ### Request Examples #### cURL Request Example ```bash curl --location 'https://app.deckflow.com/api/tools/tasks' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'files=@"archive.zip"' \ --form 'type="file.compress"' \ --form 'params="{}"' ``` #### JavaScript Request Example ```javascript const formData = new FormData(); formData.append('files', fileInput.files[0]); formData.append('type', 'file.compress'); formData.append('params', '{}'); fetch('https://app.deckflow.com/api/tools/tasks', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' }, body: formData }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python import requests url = "https://app.deckflow.com/api/tools/tasks" headers = { "Authorization": "Bearer YOUR_API_KEY" } files = [ ("files", ("archive.zip", open("archive.zip", "rb"), "application/zip")) ] data = { "type": "file.compress", "params": "{}" } response = requests.post(url, headers=headers, files=files, data=data) print(response.json()) ``` ### Response Examples #### Response 200 ```json { "id": "task-uuid-string", "spaceId": "space-default", "name": "archive.zip", "type": "file.compress", "status": "pending", "preview": null, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:00.000Z" } ``` #### Response 400 ```json { "error": { "code": "invalid_parameter", "message": "files and type are required parameters." } } ``` #### Response 401 ```json { "error": { "code": "unauthorized", "message": "Invalid API Key or authorization header." } } ``` --- ## [EN] Submit Translation Task **URL:** `https://app.deckflow.com/docs/en/api/translate.md` # Submit Translation Task > Translate presentation files (PPTX, PDF, etc.) while keeping the layout and typography intact. **HTTP Method:** `POST` **Endpoint:** `/tools/tasks` ## Interface Specification Create an asynchronous slide translation task. The value for `type` must be `translation`. POST `/tools/tasks` Try it ### Request Headers | Header | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `String` | Yes | `Bearer ` — Your developer API key. | | `Content-Type` | `String` | Yes | Must be `multipart/form-data`. | ### POST Request Body Parameters (Form Data) | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `spaceId` | `String` | No | Target workspace Space ID. | | `files` | `File` | Yes | Reference document files to translate (PPTX, Keynote, PDF, Word, Excel). Supports multiple files. | | `type` | `String` | Yes | Task type. Fixed value: `translation`. | | `name` | `String` | No | Task display name, e.g., `"AI Document Translation Task"`. | | `params` | `String (JSON)` | Yes | JSON string containing task parameters. Detailed fields below. | ## Task Parameters (params) Inner properties supported inside the `params` JSON string: | Field | Type | Required | Description | | --- | --- | --- | --- | | `from` | `String` | Yes | Source language code, e.g., `"zh"`. | | `to` | `String` | Yes | Target language code, e.g., `"en"`. | | `notifyURL` | `String` | No | Webhook callback address triggered on task status changes. | ## Supported Languages The translation API supports the following language codes for both `from` (source) and `to` (target) fields: 🔥 ### Popular | Code | Language | | --- | --- | | `en` | English | | `zh-CN` | Simplified Chinese | | `zh-TW` | Traditional Chinese | | `ja` | Japanese | | `ko` | Korean | | `es` | Spanish | 🇪🇺 ### Europe | Code | Language | | --- | --- | | `fr` | French | | `de` | German | | `it` | Italian | | `nl` | Dutch | | `ru` | Russian | | `pl` | Polish | | `sv` | Swedish | | `da` | Danish | | `fi` | Finnish | | `el` | Greek | | `cs` | Czech | | `ro` | Romanian | | `hu` | Hungarian | | `uk` | Ukrainian | 🌏 ### Asia | Code | Language | | --- | --- | | `ar` | Arabic | | `th` | Thai | | `vi` | Vietnamese | | `he` | Hebrew | 🌎 ### Americas & Others | Code | Language | | --- | --- | | `pt-BR` | Brazilian Portuguese | | `tr` | Turkish | ### Request Examples #### cURL Request Example ```bash curl --location 'https://app.deckflow.com/api/tools/tasks' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'spaceId="space-default"' \ --form 'files=@"/path/to/presentation.pptx"' \ --form 'type="translation"' \ --form 'name="AI Document Translation Task"' \ --form 'params="{\"from\":\"zh\",\"to\":\"en\"}"' ``` #### JavaScript Request Example ```javascript const formData = new FormData(); formData.append('spaceId', 'space-default'); formData.append('files', fileInput.files[0]); // presentation.pptx formData.append('type', 'translation'); formData.append('name', 'AI Document Translation Task'); formData.append('params', '{"from":"zh","to":"en"}'); fetch('https://app.deckflow.com/api/tools/tasks', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' }, body: formData }) .then(res => res.json()) .then(data => console.log(data)); ``` #### Python Request Example ```python 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/octet-stream")) ] data = { "spaceId": "space-default", "type": "translation", "name": "AI Document Translation Task", "params": '{"from":"zh","to":"en"}' } response = requests.post(url, headers=headers, files=files, data=data) print(response.json()) ``` ### Response Examples #### Response 200 ```json {{ "id": "task-uuid-string", "spaceId": "space-default", "name": "AI Document Translation Task", "type": "translation", "status": "pending", "preview": null, "createdAt": "2026-06-06T08:52:00.000Z", "updatedAt": "2026-06-06T08:52:00.000Z" }} ``` #### Response 400 ```json {{ "error": {{ "code": "invalid_parameter", "message": "type and params are required parameters." }} }} ``` #### Response 401 ```json {{ "error": {{ "code": "unauthorized", "message": "Invalid API Key or authorization header." }} }} ``` --- ## [EN] CLI Commands **URL:** `https://app.deckflow.com/docs/en/cli/commands.md` # CLI Commands > DeckUse commands operate on local PPTX workspaces. DeckOps commands operate on DeckFlow backend tasks. ## DeckUse Commands DeckUse command pattern: ```bash deckuse [options] ``` | Command | Purpose | | --- | --- | | `deckuse init [--dir ]` | Unpack a PPTX into a local DeckUse workspace. | | `deckuse status ` | Show workspace status. | | `deckuse commit [-o ]` | Build the workspace back into a PPTX. | | `deckuse list slides ` | List slides and inferred structure. | | `deckuse show slide ` | Show details for one slide. | | `deckuse get text ` | Read text from a selector. | | `deckuse set text [-o ]` | Replace text at a selector. | | `deckuse set font-size [-o ]` | Set font size in points. | | `deckuse move --left --top [-o ]` | Move matched shapes by left/top percentage. | | `deckuse replace [--slide ] [--regex] [-o ]` | Replace text globally or on one slide. | DeckUse selectors address slide and shape structure: ```bash deckuse get text ./company.deck "slide:3/title" deckuse get text ./company.deck "slide:1/shape[id=6]/shape[id=9]" deckuse get text ./company.deck "slide:1/#6,9" deckuse set text ./company.deck "shape[type=textbox]" "Updated" ``` Write behavior: - When `` is a workspace directory, write commands modify the workspace; `-o/--output` is optional and exports a PPTX if provided. - When `` is a `.pptx` file path, write commands require `-o/--output` because the CLI needs an explicit output file. - DeckUse does not render slides. Use DeckOps for rendering and format conversion. ## DeckOps Commands DeckOps command pattern: ```bash deckops [--json] [options] ``` Use `--json` for machine-readable output in scripts and agents. ### Login and Config ```bash deckops login [--port ] deckops config set-token deckops config set-space deckops config set-api-base deckops config show ``` Default callback port is `3737`. Config is stored at `~/.deckops/config.json`. ### Task Management ```bash deckops task list [--type ] [--limit ] [--offset ] deckops task get deckops task delete ``` ### Compress ```bash deckops compress [--no-wait] [--timeout ] ``` Supported inputs include `.zip`, `.pptx`, `.key`, `.docx`, `.xlsx`, `.mp4`, `.avi`, `.mov`, and `.mkv`. ### OCR ```bash deckops ocr [--language ] [--no-wait] [--timeout ] ``` Supported inputs are `.jpg`, `.jpeg`, and `.png`. Default language is `zh-hans`; supported languages include `zh-hans`, `zh-hant`, `en`, `ja`, `ko`, `ar`, `de`, `es`, `fr`, `it`, `pt`, and `ru`. ### Extract ```bash deckops extract [--type ] [--no-wait] [--timeout ] ``` Current documented extraction types map to `pptx.getFontInfo` and `pptx.getTextShapes`. ### Convert ```bash deckops convert --to \ [--width ] [--height ] \ [--need-embed-fonts [boolean]] \ [--no-wait] [--timeout ] ``` Supported output formats are `image`, `pdf`, `video`, `html`, `png`, `pptx`, and `webp`. Important conversion notes: - PPT/PPTX/PDF/KEY can render to images depending on source format. - PPT/PPTX/DOC/DOCX/KEY can convert to PDF depending on source format. - PPT/PPTX can convert to video. - KEY can convert to HTML. - HTML/Markdown can convert to PNG. - PPT/HTML can convert to PPTX. - JPG/JPEG/PNG can convert to WebP. - Multiple input files are currently supported only for HTML to PPTX conversion. - `--width`, `--height`, and `--need-embed-fonts` are relevant to HTML conversion paths. ### Create ```bash deckops create [input-files...] \ [--input-text ] \ [--enable-search [boolean]] \ [--advanced-model [boolean]] \ [--fast-mode [boolean]] \ [--intent ] \ [--audience ] \ [--page-count ] \ [--author ] \ [--no-wait] [--timeout ] ``` At least one of `--input-text` or input files is required. Up to two reference files are allowed. Supported reference extensions are `.html`, `.pdf`, `.docx`, `.pptx`, `.txt`, `.md`, `.mm`, `.xmind`, and `.ipynb`. ### Translate ```bash deckops translate \ --from \ --to \ --model \ [--use-glossary [boolean]] \ [--image-translate [boolean]] \ [--no-wait] [--timeout ] ``` Supported inputs are `.docx`, `.pptx`, `.pdf`, `.xlsx`, and `.key`. Source language supports `auto` plus common language codes; target language requires an explicit supported language code. ### Join ```bash deckops join [--name ] [--no-wait] [--timeout ] ``` Requires at least two `.pptx` files. Files are merged in command-line order. ### Run Explicit Task Type ```bash deckops run \ [--param ] \ [--no-wait] [--timeout ] ``` `--param` can be repeated. Values are parsed as JSON when possible. ### REPL ```bash deckops repl ``` Use the REPL for repeated interactive operations against the same DeckOps configuration. ## Source Basis - DeckUse GitHub README/manual/source: [https://github.com/deckflow/deckuse](https://github.com/deckflow/deckuse) - DeckOps GitHub README/source: [https://github.com/deckflow/deckops](https://github.com/deckflow/deckops) --- ## [EN] CLI Examples **URL:** `https://app.deckflow.com/docs/en/cli/examples.md` # CLI Examples > Use DeckUse for local PPTX edits. Use DeckOps for cloud tasks that need DeckFlow backend processing. ## DeckUse: Local PPTX Text Update ```bash deckuse init company.pptx --dir ./company.deck deckuse list slides ./company.deck deckuse replace ./company.deck "2025" "2026" deckuse commit ./company.deck --output company-2026.pptx ``` This workflow stays local after installation. No login, API key, backend task, or file upload is required. ## DeckUse: Inspect and Edit One Slide ```bash deckuse init roadmap.pptx --dir ./roadmap.deck deckuse show slide ./roadmap.deck 3 deckuse get text ./roadmap.deck "slide:3/title" deckuse set text ./roadmap.deck "slide:3/title" "2026 Product Roadmap" deckuse set font-size ./roadmap.deck "slide:3/title" 28 deckuse commit ./roadmap.deck --output roadmap-updated.pptx ``` Use selector expressions such as `slide:3/title`, `shape[type=textbox]`, or `slide:1/#6,9` to target existing elements. ## DeckUse: Direct PPTX Input With Explicit Output ```bash deckuse replace deck.pptx "OldBrand" "NewBrand" --output deck-brand-updated.pptx deckuse set text deck.pptx "slide:1/title" "New Launch Plan" --output deck-title-updated.pptx ``` When editing a raw `.pptx` path instead of an initialized workspace, pass `--output` so the modified deck has an explicit destination. ## DeckOps: Login and Check Tasks ```bash deckops login deckops task list --limit 10 ``` DeckOps stores credentials in `~/.deckops/config.json` and calls the DeckFlow backend for task operations. ## DeckOps: Generate a Deck ```bash deckops create \ --input-text "Please write an API design document for developers" \ --audience "Engineering Team" \ --page-count 6 ``` Use reference files when the deck should be grounded in existing material: ```bash deckops create refs.md refs.pdf \ --input-text "Generate a summary based on the reference materials" \ --audience "Management" \ --page-count 8 ``` DeckOps allows up to two reference files for `create`. ## DeckOps: Translate a Document ```bash deckops translate handbook.docx \ --from zh \ --to en \ --model Standard ``` ```bash deckops translate slides.pdf \ --from ja \ --to zh-hans \ --model Pro \ --image-translate true ``` Translation is a cloud task, so the command requires a valid DeckOps token/space and network access. ## DeckOps: Convert and Render ```bash deckops convert slides.pptx --to pdf deckops convert slides.pptx --to video --timeout 900 deckops convert page.html --to pptx --width 1920 --height 1080 --need-embed-fonts true ``` Use `--no-wait` when a task should start in the background: ```bash deckops convert slides.pptx --to pdf --no-wait --json deckops task get --json ``` ## DeckOps: Compress, OCR, and Join ```bash deckops compress presentation.pptx deckops ocr screenshot.png --language en deckops join cover.pptx chapter-1.pptx appendix.pptx --name combined-deck ``` ## Combined Workflow Use DeckUse first when edits are deterministic and local, then DeckOps when the result needs a cloud operation: ```bash deckuse init source.pptx --dir ./source.deck deckuse replace ./source.deck "2025" "2026" deckuse commit ./source.deck --output source-clean.pptx deckops convert source-clean.pptx --to pdf deckops translate source-clean.pptx --from zh --to en --model Standard ``` This split keeps simple structural edits local while reserving cloud requests for rendering, translation, OCR, generation, and other backend tasks. ## Source Basis - DeckUse GitHub: [https://github.com/deckflow/deckuse](https://github.com/deckflow/deckuse) - DeckOps GitHub: [https://github.com/deckflow/deckops](https://github.com/deckflow/deckops) --- ## [EN] CLI Install **URL:** `https://app.deckflow.com/docs/en/cli/install.md` # CLI Install > Install DeckUse for local PPTX edits, install DeckOps for cloud-backed DeckFlow tasks. Both packages require Node.js 18 or newer. ## DeckUse DeckUse is the local-first CLI. It is used for PPTX structural operations that run on local files and local workspaces. ```bash npm install -g deckuse deckuse --help ``` GitHub currently shows `npm install -g @deckflow/deckuse` in the README, but the public npm registry checked on 2026-05-27 exposes the package as `deckuse`; the scoped package `@deckflow/deckuse` was not available in the public registry at that time. Install from source if you want to run the GitHub repo directly: ```bash git clone https://github.com/deckflow/deckuse.git cd deckuse pnpm install pnpm build pnpm link --global deckuse --help ``` DeckUse does not require login, API key, space ID, or a backend URL for its core workflow. The normal flow is: ```bash deckuse init company.pptx --dir ./company.deck deckuse list slides ./company.deck deckuse replace ./company.deck "2025" "2026" deckuse commit ./company.deck --output company-2026.pptx ``` ## DeckOps DeckOps is the cloud-backed task CLI. It uploads files to the DeckFlow backend, creates tasks, optionally waits for completion, and stores authentication locally. ```bash npm install -g deckops deckops --help ``` Install from source if you want to run the GitHub repo directly: ```bash git clone https://github.com/deckflow/deckops.git cd deckops npm install npm run build node dist/cli.js --help ``` Authenticate with the browser login flow: ```bash deckops login ``` The login command opens a browser and receives the callback on `http://localhost:3737` by default. Credentials are stored in: ```text ~/.deckops/config.json ``` Common configuration fields: ```json { "token": "your-auth-token", "spaceId": "your-space-id", "apiBase": "https://app.deckflow.com/v1" } ``` You can also configure DeckOps manually: ```bash deckops config set-token deckops config set-space deckops config set-api-base https://app.deckflow.com/v1 deckops config show ``` DeckOps requires network access and valid credentials for most commands. If credentials are missing, API commands can trigger the login flow. If the backend returns `401`, DeckOps attempts re-login and retry. If the backend returns `402`, it opens checkout flow before continuing. ## Install Decision Install only `deckuse` when you need local, offline-friendly PPTX edits and do not want files sent to a cloud service. Install `deckops` when you need DeckFlow backend capabilities such as generation, translation, rendering, OCR, compression, file conversion, or long-running task management. Many workflows use both: DeckUse for local structural cleanup, then DeckOps for cloud rendering or translation. ## Source Basis - DeckUse GitHub: [https://github.com/deckflow/deckuse](https://github.com/deckflow/deckuse) - DeckUse npm package checked on 2026-05-27: [https://www.npmjs.com/package/deckuse](https://www.npmjs.com/package/deckuse) - DeckOps GitHub: [https://github.com/deckflow/deckops](https://github.com/deckflow/deckops) - DeckOps npm package checked on 2026-05-27: [https://www.npmjs.com/package/deckops](https://www.npmjs.com/package/deckops) --- ## [EN] Claude Code **URL:** `https://app.deckflow.com/docs/en/mcp/claude-code.md` # Claude Code > Connect DeckFlow to Claude Code via MCP so terminal-based agents can create, revamp, translate, convert, extract, merge, split, and optimize presentation files. Use this guide when the user wants DeckFlow available inside Claude Code projects. This page follows the same structure as the HeyGen Claude Code MCP guide, with DeckFlow-specific API key transport details still to confirm. ## Prerequisites - Claude Code installed. - Node.js installed, if required by the active Claude Code MCP resolution path. - A DeckFlow account with MCP access. - A DeckFlow API key. - Permission to upload or reference files used in DeckFlow workflows. ## Add The MCP Server Run this command in your terminal, outside the Claude Code interactive session: ```text claude mcp add --transport http deckflow https://dev.deckflow.com/mcp/v1/ ``` To make DeckFlow available across all Claude Code projects, add the user scope flag: ```text claude mcp add --transport http -s user deckflow https://dev.deckflow.com/mcp/v1/ ``` ## Alternative: Direct Config Edit If the target Claude Code version supports direct config editing, add DeckFlow to `~/.claude.json`: ```json { "mcpServers": { "deckflow": { "type": "http", "url": "https://dev.deckflow.com/mcp/v1/" } } } ``` Restart Claude Code after editing the config file. ## Authentication DeckFlow MCP uses API key authentication only. The final docs still need to define how Claude Code should pass the API key to the remote MCP server. Possible patterns include client secret configuration, HTTP header configuration, or an MCP auth prompt. The user can run the MCP status view inside Claude Code: ```text /mcp ``` This page still needs the final credential storage instructions, API key creation URL, and environment variable or header name. ## Verify The Connection After setup, confirm the server is active: ```text claude mcp list ``` Or from inside Claude Code: ```text /mcp ``` The user should see `deckflow` listed with a connected status and available tools. ## Usage Example prompt: ```text Use DeckFlow to turn this research PDF into a 10-slide PPTX deck, then tell me when the generated file is ready. ``` Claude Code should call the appropriate DeckFlow MCP tool, poll the task, and return the generated file as a temporary download link. ## Recommended Agent Instructions For better results, ask Claude Code to inspect DeckFlow capabilities before submitting file tasks: ```text Before using DeckFlow, call the available capability or account tool to confirm supported input formats, output formats, file limits, and whether Create, Revamp, Translate, and Tools are available. ``` ## Scoping | Scope | Flag | Config Location | Availability | | --- | --- | --- | --- | | Local | none | `.mcp.json` in project directory | Current project only | | User | `-s user` | `~/.claude.json` | All projects for current user | ## Parameters To Confirm | Parameter | Question | | --- | --- | | API key creation | Where does the user create or copy the DeckFlow API key? | | API key transport | Should Claude Code pass the key through a header, secret field, env var, or prompt? | | Credential storage | What env var and config file should be documented? | | Verification tool | Should docs recommend `get_current_user`, `get_deckflow_capabilities`, or another health check? | | Output handling | Temporary download links are confirmed. Should outputs also be saved in a DeckFlow workspace? | --- ## [EN] Claude Web / Desktop **URL:** `https://app.deckflow.com/docs/en/mcp/claude-web.md` # Claude Web / Desktop > Connect DeckFlow to Claude through a custom MCP connector so users can run presentation and document workflows directly inside Claude chats. This page adapts the HeyGen Claude Web MCP setup structure for DeckFlow. Final screenshots, API key transport, and plan requirements still need confirmation. ## Prerequisites - A Claude plan that supports custom connectors. - A DeckFlow account with MCP access. - A DeckFlow API key. - Permission to upload or reference files in Claude. ## Setup ### 1. Register The Connector In Claude, navigate to the custom connector settings. The current HeyGen reference path is: ```text + -> Connector -> Manage Connector -> + Add custom connector ``` Set the connector name to: ```text DeckFlow ``` Set the remote MCP server URL to: ```text https://dev.deckflow.com/mcp/v1/ ``` ### 2. Authenticate After saving the connector, click **Connect**. DeckFlow MCP uses API key authentication only. Claude must support the required secret input flow, HTTP header configuration, or another approved way to send the DeckFlow API key to the remote MCP server. If Claude custom connectors cannot pass API keys securely, DeckFlow may need a first-party connector or an intermediate key exchange. ### 3. Configure Permissions Claude may ask for permission before tool calls. For smoother workflows, users can allow DeckFlow tools for the current chat or connector, depending on Claude's permission model. The final docs should explain that DeckFlow tools may upload files, create derived files, read task status, and return downloadable outputs. ## Usage Example prompt: ```text Use DeckFlow to translate this deck into Japanese while preserving layout, then return the translated file. ``` Claude should choose the matching DeckFlow MCP tool, submit the task, poll until complete, and return the result. ## Suggested First Test Use a low-risk capability discovery prompt: ```text Use DeckFlow MCP to list the supported workflows, input formats, output formats, and file size limits available to this account. ``` ## Limitations To Document | Constraint | Detail To Confirm | | --- | --- | | Claude plan | Which Claude plans support custom MCP connectors at publish time? | | DeckFlow plan | Which DeckFlow plans include MCP access? | | API key setup | Where Claude users enter or store the DeckFlow API key. | | File attachments | Whether Claude passes attached files directly to MCP or DeckFlow needs upload URLs. | | Permission prompts | Whether users can set DeckFlow tools to always allow. | | Output links | Temporary download links are confirmed; confirm signed URL lifetime. | ## Parameters To Confirm | Parameter | Question | | --- | --- | | Connector name | Should it be documented as `DeckFlow`, `deckflow`, or another display name? | | API key transport | Can Claude custom connectors send the DeckFlow API key securely, and how should users configure it? | | Screenshots | Do we have DeckFlow-specific Claude screenshots to include? | | Plan requirements | What Claude and DeckFlow plans should be listed? | --- ## [EN] MCP Confirmation Questions **URL:** `https://app.deckflow.com/docs/en/mcp/confirmation-questions.md` # MCP Confirmation Questions > Questions for DeckFlow product/API owners before replacing MCP placeholders with final values. Please answer these before the MCP docs move from draft to implementation-ready reference. ## Confirmed So Far | Area | Confirmed Value | | --- | --- | | MCP endpoint | `https://dev.deckflow.com/mcp/v1/` | | Authentication | API key only | | First-batch client pages | `claude-code`, `claude-web`, `manus`, `open-ai` | | Output delivery | Temporary download links | ## 1. Endpoint And Transport 1. Is `https://dev.deckflow.com/mcp/v1/` the public production endpoint or a dev/beta endpoint? 2. Are there staging, regional, or additional versioned endpoints? 3. Should examples always include the trailing slash? 4. Is DeckFlow remote HTTP MCP only, or will there also be SSE, stdio, or local server support? 5. Should the canonical MCP config key be `deckflow`, `DeckFlow`, or another name? ## 2. Authentication 1. Where do users create or copy a DeckFlow API key? 2. What header, secret field, or environment variable should clients use for the API key? 3. Should docs standardize on an env var such as `DECKFLOW_API_KEY`, or use client-specific secret configuration only? 4. Are API keys personal, workspace-scoped, organization-scoped, or project-scoped? 5. How do users revoke or rotate a DeckFlow API key? ## 3. Official Client Support 1. Confirm that launch docs should include only Claude Code, Claude Web/Desktop, Manus, and OpenAI/ChatGPT. 2. Should Cursor receive a dedicated page later even though HeyGen only mentions it in overview? 3. Do any clients require domain whitelisting, app registration, or private beta access? 4. Which client pages need screenshots before publishing? ## 4. Tool Naming 1. Are `create_deck`, `revamp_deck`, and `translate_deck` acceptable final tool names? 2. Should Tools use grouped tools like `convert_file`, `extract_file_content`, `compose_files`, and `optimize_file`, or one tool per browser tool? 3. What are the final task tools: `get_task`, `list_tasks`, `cancel_task`, and `get_task_result`, or different names? 4. Is `get_deckflow_capabilities` the preferred discovery tool name? 5. Should there be `get_current_user`, `list_brand_profiles`, `list_templates`, `list_glossaries`, and `list_supported_languages` tools? ## 5. File Input And Output 1. How should agents pass files: MCP attachments, DeckFlow upload IDs, pre-signed upload URLs, external URLs, inline content, or a mix? 2. Can agents pass local file paths from terminal clients, or must they upload first? 3. How long are input files retained? 4. Temporary download links are confirmed. What is the signed URL lifetime? 5. Are outputs also persisted in a DeckFlow workspace, or only available through temporary links? ## 6. Task Lifecycle 1. What is the task status enum? 2. Does every task return progress percentage, stage name, ETA, or only status? 3. Which tasks can be cancelled? 4. Are idempotency keys supported to prevent duplicate submissions? 5. What is the standard error schema? ## 7. Product Workflow Parameters 1. What are the final Create input source types and output formats? 2. What Create parameters should exist for slide count, aspect ratio, language, Brand DNA, template, and complex element preservation? 3. What Revamp parameters should exist for style mode, template, Brand DNA, content preservation, batch mode, and output format? 4. What Translate parameters should exist for target language, source language, glossary, layout preservation, same-format output, and image text translation? 5. Which parameters are required, optional, or defaulted by DeckFlow? ## 8. Limits And Billing 1. Do MCP workflows use the same file limits as the public browser tools? 2. What are the maximum files per task, total batch size, slide count, page count, video duration, and inline prompt length? 3. What are the rate limits and concurrent task limits? 4. Which DeckFlow plans include MCP access? 5. How are credits consumed for completed, failed, cancelled, or partially successful tasks? ## 9. Security And Compliance 1. Should the docs state AES-256 encryption and post-processing deletion for MCP uploads too? 2. Are MCP inputs used for model training? 3. Are there workspace audit logs for MCP task creation and downloads? 4. Are there admin controls for enabling/disabling MCP? 5. Are any file types or domains blocked for security reasons? ## 10. Publishing 1. Which placeholders can be replaced now? 2. Which pages should remain internal until integrations are live? 3. Should examples include real screenshots, or text-only setup first? 4. Should docs use `OpenAI`, `ChatGPT`, or `OpenAI / ChatGPT` as the page title? 5. Who signs off on endpoint, billing, and retention language? --- ## [EN] MCP Examples **URL:** `https://app.deckflow.com/docs/en/mcp/examples.md` # MCP Examples > Example prompts and expected tool flows for agents using DeckFlow MCP. These examples are written as product documentation drafts. Tool names and parameters are placeholders until the final MCP schema is confirmed. ## Create A Deck From Research Material User prompt: ```text Use DeckFlow to turn this research PDF into a 12-slide investor-ready deck. Keep technical charts readable, use a concise executive tone, and export PPTX. ``` Expected agent flow: 1. Confirm the attached file is a supported Create source. 2. Call `create_deck` with the source file, requested slide count, audience, tone, and PPTX output. 3. Poll `get_task` until the task completes. 4. Return the PPTX temporary download link and mention any warnings, such as missing fonts or chart fidelity issues. Parameters the user or agent should provide: | Parameter | Example | | --- | --- | | `source_type` | `file` | | `source` | Attached PDF | | `slide_count` | `12` | | `audience` | `investors` | | `tone` | `executive, concise` | | `output_format` | `pptx` | ## Create A Deck From A URL User prompt: ```text Create a short product overview deck from this URL and export both PPTX and PDF. ``` Expected agent flow: 1. Check whether URL import is supported. 2. Call `create_deck` with `source_type=url`. 3. Request multiple output formats if supported, or run export after creation. 4. Return both temporary download links. Parameters still to define: | Parameter | Open Question | | --- | --- | | `source_url` | Are public URLs only supported, or can authenticated pages be imported? | | `output_format` | Can one task return multiple formats? | | `crawl_depth` | Is URL import limited to one page or can it follow links? | ## Revamp An Existing Deck User prompt: ```text Use DeckFlow to revamp this PPTX with our saved Brand DNA. Do not rewrite the content. Keep the final output editable. ``` Expected agent flow: 1. Call `list_brand_profiles` if the user does not specify a Brand DNA profile. 2. Call `revamp_deck` with the selected brand profile and `preserve_content=true`. 3. Poll task status. 4. Return the editable output file as a temporary download link. Parameters the user or agent should provide: | Parameter | Example | | --- | --- | | `file` | Attached PPTX | | `style_mode` | `brand_dna` | | `brand_profile_id` | Selected profile | | `preserve_content` | `true` | | `output_format` | `pptx` | ## Translate Without Breaking Layout User prompt: ```text Translate this Keynote deck into Japanese. Keep the layout intact and use our product glossary. ``` Expected agent flow: 1. Validate that Keynote input is supported. 2. Call `list_glossaries` if the user does not name a glossary ID. 3. Call `translate_deck` with target language and glossary. 4. Poll until complete. 5. Return the translated file as a temporary download link, along with any layout warnings. Parameters the user or agent should provide: | Parameter | Example | | --- | --- | | `file` | Attached Keynote file | | `target_language` | `ja` | | `glossary_id` | Selected glossary | | `preserve_layout` | `true` | | `output_format` | Same as input, if supported | ## Convert HTML To PPTX User prompt: ```text Use DeckFlow to convert this HTML page into an editable PowerPoint deck. ``` Expected agent flow: 1. Use `convert_file` with `operation=html_to_pptx`. 2. Pass either uploaded HTML or pasted HTML content. 3. Return the generated PPTX as a temporary download link. Parameters the user or agent should provide: | Parameter | Example | | --- | --- | | `operation` | `html_to_pptx` | | `file` or `content` | HTML file or pasted HTML | | `output_format` | `pptx` | ## Extract Text Shapes From PPTX User prompt: ```text Extract all text boxes from slides 3 through 10 of this PPTX and return structured JSON. ``` Expected agent flow: 1. Call `extract_file_content` with `operation=pptx_text_extractor`. 2. Set `page_range` or `slide_range` to slides 3 through 10. 3. Request structured output. 4. Return JSON or a downloadable JSON file. Parameters still to define: | Parameter | Open Question | | --- | --- | | `page_range` vs `slide_range` | Which name should the API/MCP use consistently? | | `include_coordinates` | Should shape positions be returned by default? | | `output_format` | Inline JSON response or generated JSON file? | ## Merge Several PPTX Files User prompt: ```text Merge these three PPTX files in the order uploaded. Keep each deck's original formatting as much as possible. ``` Expected agent flow: 1. Preserve the upload order or ask the user to confirm ordering. 2. Call `compose_files` with `operation=pptx_merge`. 3. Poll until complete. 4. Return the merged deck as a temporary download link. Parameters the user or agent should provide: | Parameter | Example | | --- | --- | | `operation` | `pptx_merge` | | `files` | Ordered PPTX file references | | `preserve_styles` | `true` | | `output_name` | Optional filename | ## Compress A Delivery Package User prompt: ```text Compress this PPTX so I can email it, but keep image quality high. ``` Expected agent flow: 1. Call `optimize_file` with `operation=file_compress`. 2. Choose a conservative compression preset. 3. Return the compressed file as a temporary download link, plus before/after size if available. Parameters still to define: | Parameter | Open Question | | --- | --- | | `quality` | Preset enum or numeric value? | | `target_size_mb` | Should the user be able to request a max size? | | `size_report` | Should the result include before/after byte size? | ## Agent Behavior Guidelines Agents should ask a follow-up question when: - The source file is missing. - The user requests a Brand DNA profile, template, or glossary but has not specified which one and no default exists. - The output format is unsupported or ambiguous. - The task could overwrite or delete an existing workspace asset. - Multiple files are attached and ordering matters. Agents should proceed without extra questions when: - The user attached exactly one compatible file. - The requested operation and output format are clear. - DeckFlow capabilities can be discovered through `get_deckflow_capabilities`. - Sensible defaults are defined by the final schema. ## Example Capability Discovery Prompt ```text Use DeckFlow MCP to inspect available capabilities, then tell me which operations support PPTX input and which output formats each one can produce. ``` Expected agent flow: 1. Call `get_deckflow_capabilities`. 2. Filter capabilities where input formats include PPTX. 3. Summarize supported outputs and limits. --- ## [EN] Manus **URL:** `https://app.deckflow.com/docs/en/mcp/manus.md` # Manus > Connect DeckFlow to Manus agents so automated workflows can create, revamp, translate, convert, and optimize presentation files without manual handoff. This page adapts the HeyGen Manus MCP guide pattern for DeckFlow. The final Manus integration path depends on whether DeckFlow appears as a first-party Manus tool or is added through a custom MCP endpoint. ## Prerequisites - A Manus account with agent access. - A DeckFlow account with MCP access. - A DeckFlow API key, unless the Manus integration stores it through a managed connector. - A confirmed DeckFlow integration path in Manus. - Permission to upload or reference source files used by the agent. ## Connect DeckFlow Connection path is **TBD** for Manus-specific UI, but the confirmed DeckFlow MCP endpoint is: ```text https://dev.deckflow.com/mcp/v1/ ``` If DeckFlow is available as a built-in Manus tool: 1. Open Manus. 2. Go to **Connect Your Tools**. 3. Search for `DeckFlow`. 4. Click **Connect**. 5. Configure the DeckFlow API key if the managed connector asks for one. If Manus requires a custom MCP endpoint: 1. Open the Manus tool or integration settings. 2. Add a custom MCP server named `DeckFlow`. 3. Set the endpoint to `https://dev.deckflow.com/mcp/v1/`. 4. Configure the DeckFlow API key using the supported Manus secret or connector flow. ## Use DeckFlow In A Manus Agent Open the agent workspace and select the DeckFlow tools for the agent. Then write a natural-language task describing the desired workflow. Example prompt: ```text Every Monday morning, collect the latest product notes from the workspace, use DeckFlow to create a concise internal update deck, export PPTX and PDF, and send me the temporary download links. ``` Manus should orchestrate source collection, submit the DeckFlow task, monitor progress, and deliver the result package. ## Scheduled Or Unattended Workflows Manus-style agents are useful for recurring DeckFlow tasks: - Generate weekly status decks from notes or reports. - Translate sales decks for regional teams. - Revamp old decks using the latest Brand DNA. - Compress delivery packages before sending to customers. - Extract PPTX text or font usage for audit workflows. The final docs should state whether DeckFlow MCP allows unattended execution and how API key scope, file retention, and billing work for scheduled agents. ## Recommended Agent Instructions ```text Before using DeckFlow, confirm the workflow type, input files, output format, and target workspace. For scheduled jobs, report task IDs, warnings, output links, and any failed files. ``` ## Parameters To Confirm | Parameter | Question | | --- | --- | | Manus path | Is DeckFlow a built-in Manus tool, custom MCP connector, or both? | | API key transport | How does Manus store and send the DeckFlow API key? | | Scheduled jobs | Are recurring/unattended tasks supported by DeckFlow policy? | | Output delivery | Temporary download links are confirmed. Should Manus attach files or save outputs to a DeckFlow workspace too? | --- ## [EN] OpenAI / ChatGPT **URL:** `https://app.deckflow.com/docs/en/mcp/open-ai.md` # OpenAI / ChatGPT > Add DeckFlow to ChatGPT or OpenAI agent surfaces so users can run presentation and document workflows from conversation. This page adapts the HeyGen OpenAI MCP/App guide pattern for DeckFlow. The exact setup depends on whether DeckFlow is distributed as a ChatGPT app, a custom MCP connector, or an OpenAI agent tool integration. ## Prerequisites - A ChatGPT or OpenAI account with access to the target app/tool integration surface. - A DeckFlow account with MCP access. - A DeckFlow API key, unless the app integration handles key storage. - A confirmed DeckFlow OpenAI integration path. - Permission to upload or reference presentation, document, image, HTML, or video files. ## Setup Option A: DeckFlow App Use this path if DeckFlow is published as a ChatGPT app. 1. Open ChatGPT. 2. Go to the Apps or connectors area. 3. Search for `DeckFlow`. 4. Select the official DeckFlow app. 5. Click **Connect**. 6. Configure the DeckFlow API key if the app asks for one. The final docs should include the official app URL after publication. ## Setup Option B: Custom MCP Connector Use this path if ChatGPT or the target OpenAI surface supports custom MCP connectors. 1. Open connector settings. 2. Add a custom connector named `DeckFlow`. 3. Set the remote MCP endpoint to: ```text https://dev.deckflow.com/mcp/v1/ ``` 1. Save the connector. 2. Configure the DeckFlow API key using the supported OpenAI/ChatGPT secret or connector flow. ## Usage Example prompt: ```text Use DeckFlow to revamp this sales deck with our default Brand DNA, keep the content unchanged, and return an editable PPTX. ``` The agent should call DeckFlow tools, monitor the async task, and return generated outputs as temporary download links. ## Good Prompt Patterns - Include the source file or URL. - Name the workflow: Create, Revamp, Translate, Convert, Extract, Merge, Split, or Optimize. - Specify output format, such as PPTX, PDF, PNG, WebP, HTML, MP4, JSON, or ZIP. - Mention design or language constraints, such as Brand DNA, template, target language, or glossary. - Ask the agent to report warnings if layout, fonts, charts, or images need attention. ## Parameters To Confirm | Parameter | Question | | --- | --- | | OpenAI surface | Is DeckFlow intended for ChatGPT Apps, custom MCP, Assistants/Agents, or multiple surfaces? | | App URL | What is the official ChatGPT app URL, if any? | | API key transport | How should OpenAI/ChatGPT send the DeckFlow API key to MCP? | | File attachments | Can ChatGPT pass attached files to DeckFlow directly, or does DeckFlow need a separate upload step? | | Plan requirements | Which OpenAI/ChatGPT and DeckFlow plans are required? | --- ## [EN] MCP Parameter Checklist **URL:** `https://app.deckflow.com/docs/en/mcp/parameter-checklist.md` # MCP Parameter Checklist > Product/API decisions needed before DeckFlow MCP docs can become final tool documentation. This page collects the missing parameters discovered while drafting `index.md`, `setup.md`, `tools.md`, and `examples.md`. For direct questions to ask product/API owners, see `confirmation-questions.md`. ## Confirmed Values | Area | Confirmed Value | | --- | --- | | MCP endpoint | `https://dev.deckflow.com/mcp/v1/` | | Authentication | API key only | | First-batch clients | Claude Code, Claude Web/Desktop, Manus, OpenAI/ChatGPT | | Output delivery | Temporary download links | ## Connection | Parameter | Needed Definition | | --- | --- | | MCP endpoint | Whether `https://dev.deckflow.com/mcp/v1/` is production or dev/beta, plus staging/regional/versioning policy. | | Transport | Remote HTTP only, SSE support, stdio/local server support, or multiple modes. | | Server name | Canonical config key: `deckflow`, `DeckFlow`, or another name. | | Capability discovery | Whether `get_deckflow_capabilities` exists and what it returns. | ## Authentication And Permissions | Parameter | Needed Definition | | --- | --- | | Auth method | Confirmed API key only. Still need key creation URL, header/env var, and client-specific secret handling. | | API key scopes | File upload, task creation, task read, workspace read, glossary read, Brand DNA read, billing read, if scoped keys exist. | | Workspace scope | Personal account, team workspace, organization, or project. | | Token lifetime | Expiration, refresh, reconnect, logout, and revocation behavior. | | Domain/app allowlist | Whether custom agents need domain whitelisting or app registration. | | User identity tool | Final name and response shape for current user/account lookup. | ## File Input | Parameter | Needed Definition | | --- | --- | | File reference model | `file_id`, `asset_id`, signed upload URL, client attachment ID, external URL, or inline content. | | Upload limits | Max size, max files per task, total batch size, page count, slide count, video duration. | | Supported MIME types | Canonical MIME and extension list for each workflow. | | URL import | Public URLs only, authenticated URLs, allowed domains, crawl depth, and timeout. | | Inline content | Max length for pasted HTML, Markdown, text, and prompt fields. | | Retention | How long uploaded inputs are stored and when they are deleted. | ## Common Task Lifecycle | Parameter | Needed Definition | | --- | --- | | Task ID | Format, stability, workspace visibility, and expiration. | | Status enum | Canonical states for queueing, processing, success, failure, cancellation, and expiration. | | Progress | Percent, stage labels, ETA, current step, or no progress. | | Cancellation | Which tools support cancellation and when cancellation is allowed. | | Retry behavior | Client retry rules, idempotency key support, and duplicate task prevention. | | Webhooks | Whether MCP tasks can register callbacks or only support polling. | | Error schema | Error code, message, retryable flag, field-level validation errors, and support trace ID. | ## Output Delivery | Parameter | Needed Definition | | --- | --- | | Result model | Files, previews, metadata, warnings, logs, and nested assets. | | Download URLs | Temporary signed URL lifetime, access control, filename, and content type. | | Multiple outputs | How PPTX + PDF or image batches are represented. | | ZIP packaging | When multi-file outputs are zipped and how users request it. | | Workspace persistence | Whether outputs appear in the DeckFlow web app/project library. | | Result expiration | How long outputs stay downloadable. | ## Create | Parameter | Needed Definition | | --- | --- | | `source_type` | Enum for file, URL, text, Markdown, topic, or mixed sources. | | `source` | File reference, URL, inline content, or multiple sources. | | `prompt` | Max length, required/optional behavior, and prompt safety rules. | | `output_format` | PPTX, PDF, HTML, image, or multiple output formats. | | `slide_count` | Exact number, min/max range, or agent-estimated default. | | `aspect_ratio` | Supported ratios and default. | | `brand_profile_id` | Brand DNA ID format and default profile behavior. | | `template_id` | Template catalog, compatibility, and preview support. | | `language` | Language code standard and auto-detection behavior. | | Complex element handling | Defaults for formulas, charts, diagrams, images, tables, and nested structures. | ## Revamp | Parameter | Needed Definition | | --- | --- | | Input formats | PPTX, Keynote, PDF, and whether PPT is accepted. | | `style_mode` | Template, Brand DNA, custom instructions, or auto style. | | `template_id` | Template list, filtering, preview, and compatibility. | | `brand_profile_id` | Brand DNA availability, selection, and fallback. | | `preserve_content` | Whether content preservation is always enforced or configurable. | | Batch revamp | Max files, ordering, output packaging, and per-file failures. | | Output formats | Same as input, PPTX only, PDF, Keynote, or multiple. | ## Translate | Parameter | Needed Definition | | --- | --- | | Supported languages | Canonical list, language codes, locale variants, and right-to-left support. | | `source_language` | Optional, required, or auto-detected. | | `target_language` | Required field format. | | Glossary model | `glossary_id`, inline terms, CSV upload, term case sensitivity, and priority. | | Layout preservation | Defaults and warning behavior when translated text cannot fit. | | Same-format output | Whether input format is always preserved or can be changed. | | Image text translation | Whether OCR text inside images is translated by default. | | Speaker notes/comments | Whether notes and comments are translated. | ## Converter Tools | Parameter | Needed Definition | | --- | --- | | `operation` enum | Final names for 13 converter operations. | | HTML render options | Viewport, scale, wait time, external assets, fonts, and page height behavior. | | PPT/video options | Duration per slide, animation handling, transition handling, resolution, FPS. | | Image output options | PNG/JPEG/WebP, scale, page range, ZIP packaging, and naming. | | Legacy PPT handling | Whether PPT input is converted directly or normalized to PPTX first. | ## Extractor Tools | Parameter | Needed Definition | | --- | --- | | OCR languages | Auto-detection, language hints, and supported scripts. | | OCR output | Plain text, JSON blocks, coordinates, confidence, reading order. | | PPTX font output | Font family, style, weight, slide usage, missing-font detection. | | PPTX text output | Shape IDs, slide numbers, coordinates, style metadata, speaker notes. | | Range parameter | Standardize on `page_range`, `slide_range`, or `ranges`. | ## Merger And Splitter | Parameter | Needed Definition | | --- | --- | | Merge order | Upload order, explicit order array, or filename sort. | | Style preservation | How themes, masters, fonts, and duplicate assets are handled. | | Split strategy | Split every slide, selected ranges, fixed chunk size, or named sections. | | HTML player package | Canvas size, title, description, navigation, and asset packaging. | | Partial failure | Behavior when one input file fails validation. | ## Optimizer | Parameter | Needed Definition | | --- | --- | | Compression quality | Presets, numeric ranges, defaults, and min quality. | | Target size | Whether users can request a max MB output and what happens if impossible. | | Image resize | Width/height rules, aspect ratio lock, upscaling policy, output type. | | Font embedding | Font file upload, licensing warnings, subsetting, and font selection. | | Video compression | Codec, bitrate, resolution, FPS, audio handling, and target format. | ## Limits And Billing | Parameter | Needed Definition | | --- | --- | | Plan access | Which DeckFlow plans can use MCP. | | Credits | How tasks consume credits and how failed/cancelled tasks are charged. | | Rate limits | Requests per minute, tasks per hour, concurrent jobs, batch limits. | | Free tier | Whether MCP is available and with which limits. | | Usage reporting | Whether agents can query remaining credits or task history. | ## Documentation Publishing Checklist - Confirm whether `https://dev.deckflow.com/mcp/v1/` is final production or dev/beta. - Confirm final tool names and remove "proposed" language. - Add final JSON schemas or link to generated reference pages. - Add real client screenshots only after integrations exist. - Confirm security, retention, billing, and plan language with product/legal. - Confirm examples against a working MCP server before publishing. --- ## [EN] MCP Setup **URL:** `https://app.deckflow.com/docs/en/mcp/setup.md` # MCP Setup > Configure DeckFlow MCP in AI clients so agents can run presentation and file workflows from chat, code, or automated agent sessions. This page is a setup draft. It mirrors the shape of the HeyGen MCP setup pages, while using the confirmed DeckFlow endpoint, API key-only auth model, first-batch clients, and temporary download-link output model. ## Prerequisites - A DeckFlow account. - Access to the DeckFlow MCP beta or production integration. - An MCP-compatible client that supports remote HTTP MCP servers. - A DeckFlow API key. - Permission to upload or reference source files used in Create, Revamp, Translate, and Tools workflows. ## Endpoint ```text https://dev.deckflow.com/mcp/v1/ ``` The docs currently use this endpoint exactly as provided. Confirm later whether this is the final production URL or a development endpoint. ## Dedicated Client Guides Use the dedicated pages for client-specific setup details: | Client | Page | | --- | --- | | Claude Code | `claude-code.md` | | Claude Web / Desktop | `claude-web.md` | | Manus | `manus.md` | | OpenAI / ChatGPT | `open-ai.md` | This page remains the shared setup overview and fallback for generic MCP-compatible clients. ## Authentication DeckFlow MCP uses API key authentication only. The final setup guide still needs the API key details: | API Key Detail | What The Docs Must Explain | | --- | --- | | Key creation URL | Where users create or copy a DeckFlow API key. | | Secret name | Whether clients should use the `Authorization` request header (in the form of `Bearer `). | | Transport | Whether the key is passed through MCP client secret config, HTTP header config, or an auth prompt. | | Scope | Whether keys are personal, workspace-scoped, organization-scoped, or project-scoped. | | Rotation | How users revoke or rotate keys. | ## Claude Code Run the command from a terminal, outside the Claude Code interactive session: ```text claude mcp add --transport http deckflow https://dev.deckflow.com/mcp/v1/ ``` To install it globally for all Claude Code projects: ```text claude mcp add --transport http -s user deckflow https://dev.deckflow.com/mcp/v1/ ``` After adding the server, restart Claude Code or run the client-specific MCP refresh command if available. ### Alternative Config If direct config editing is supported in the target Claude Code version, the MCP server should look like this: ```json { "mcpServers": { "deckflow": { "type": "http", "url": "https://dev.deckflow.com/mcp/v1/" } } } ``` ## Claude Web / Desktop 1. Open the connector or integration settings. 2. Add a custom connector named `DeckFlow`. 3. Set the remote MCP server URL to: ```text https://dev.deckflow.com/mcp/v1/ ``` 1. Save the connector. 2. Configure the DeckFlow API key using Claude's supported secret or connector flow. 3. Allow the DeckFlow tools when the client asks for tool permissions. ## Other MCP Clients The confirmed first-batch DeckFlow client list is Claude Code, Claude Web/Desktop, Manus, and OpenAI/ChatGPT. Other MCP-compatible clients can be documented later using the generic pattern below after product support is confirmed. For clients that accept a JSON MCP server definition, use the same remote HTTP structure: ```json { "mcpServers": { "deckflow": { "type": "http", "url": "https://dev.deckflow.com/mcp/v1/" } } } ``` If a client uses a different field name, map the final endpoint to its remote MCP URL field. ## Verify The Connection Use the MCP client's server list or tool discovery command to confirm: - The `deckflow` server appears in the connected servers list. - DeckFlow tools are visible. - The client has access to a valid DeckFlow API key. - A simple account or capability check succeeds, if DeckFlow provides one. Suggested verification tool, if implemented: ```text get_current_user ``` or: ```text get_deckflow_capabilities ``` Both names are placeholders until the final tool schema is defined. ## First Prompt After setup, test with a low-risk task: ```text Use DeckFlow to list the available MCP capabilities and tell me which file formats are supported for Create, Revamp, Translate, and file conversion. ``` Then test a file workflow: ```text Use DeckFlow to convert this PowerPoint deck to PDF and return the temporary download link. ``` ## Client Permission Notes MCP clients may ask for permission before each tool call. For smoother workflows, users can usually allow DeckFlow tools for the current chat, project, or workspace. The final docs should explain permission scope carefully because DeckFlow tools can upload files, create derived files, and return downloadable outputs. ## Setup Parameters To Define | Parameter | Required Before Publishing | | --- | --- | | Endpoint semantics | Whether `https://dev.deckflow.com/mcp/v1/` is the public production endpoint or a development/beta endpoint. | | Server name | Confirm `deckflow` as the canonical config key. | | API key transport | Header name, env var name, secret field name, and client-specific setup mechanism. | | Account scope | Personal workspace, team workspace, organization selection, or project selection. | | Tool permission policy | Recommended allow/deny settings for clients that prompt before tool calls. | | File upload path | Whether files are uploaded through MCP, imported by URL, or passed through client attachments. | | Connection test | Final health/account/capability tool name. | | Supported clients | Which clients are officially supported vs. generic MCP-compatible. | For the direct product/API questions, see `confirmation-questions.md`. --- ## [EN] MCP Tools **URL:** `https://app.deckflow.com/docs/en/mcp/tools.md` # MCP Tools > Draft DeckFlow MCP tool catalog for AI agents. Tool names and schemas below are proposed documentation scaffolding, not final implementation contracts. DeckFlow MCP should expose both product-level workflows and single-purpose file tools. The most important design choice is whether the final MCP server uses many narrow tools or fewer generic task tools with operation enums. Recommended approach for agents: use a small set of workflow tools for Create, Revamp, and Translate, plus grouped tools for file conversion, extraction, merge/split, and optimization. This keeps the MCP surface readable while still covering the 23 public browser tools. ## Common Task Model Most DeckFlow operations should return a task object first, then let the agent poll status and fetch results. | Proposed Tool | Description | | --- | --- | | `get_task` | Get task status, progress, warnings, errors, and result metadata. | | `list_tasks` | List recent tasks for the authenticated user or workspace. | | `cancel_task` | Cancel a queued or running task when supported. | | `get_task_result` | Retrieve output files, previews, download URLs, and metadata for a completed task. | ### Common Parameters To Define | Parameter | Purpose | Required Decision | | --- | --- | --- | | `task_id` | Identifies an async job. | ID format, visibility scope, and expiration. | | `status` | Shows lifecycle state. | Enum such as `queued`, `running`, `succeeded`, `failed`, `cancelled`, `expired`. | | `progress` | Indicates completion. | Percent, stage name, ETA, or all three. | | `result_urls` | Provides generated files as temporary download links. | Signed URL lifetime and whether files also persist in workspace. | | `warnings` | Reports non-fatal issues. | Warning codes for missing fonts, layout changes, unsupported media, etc. | | `error` | Reports failure. | Error schema, retryability, user-facing message, and developer code. | ## Product Workflow Tools ### Create | Proposed Tool | Description | | --- | --- | | `create_deck` | Generate a deck from uploaded files, URLs, pasted text, Markdown, or a topic prompt. | Expected inputs: | Parameter | Description | Status | | --- | --- | --- | | `source_type` | Input type such as `file`, `url`, `text`, `markdown`, or `topic`. | Needs enum. | | `source` | File reference, URL, or text payload. | Needs file reference model. | | `prompt` | User instructions for structure, audience, tone, and emphasis. | Needs max length. | | `output_format` | PPTX, PDF, HTML, or image. | Needs enum and defaults. | | `brand_profile_id` | Optional Brand DNA profile to apply. | Needs Brand DNA model. | | `theme_or_template_id` | Optional template or design style. | Needs template catalog. | | `slide_count` | Desired number or range of slides. | Needs limits and defaults. | | `aspect_ratio` | Presentation ratio such as 16:9 or 4:3. | Needs enum. | | `language` | Output language. | Needs language code standard. | | `preserve_complex_elements` | Whether to preserve formulas, charts, images, and nested structures. | Needs default behavior. | ### Revamp | Proposed Tool | Description | | --- | --- | | `revamp_deck` | Redesign an existing deck while preserving original text, data, and structure. | Expected inputs: | Parameter | Description | Status | | --- | --- | --- | | `file` | PPTX, Keynote, or PDF source deck. | Needs file reference model. | | `style_mode` | `template` or `brand_dna`. | Needs enum. | | `template_id` | Professional template to apply. | Needs template catalog. | | `brand_profile_id` | Brand DNA profile to apply. | Needs Brand DNA model. | | `preserve_content` | Whether original content must remain unchanged. | Should likely default to `true`. | | `output_format` | Result format. | Needs enum; likely same type or PPTX/PDF. | | `batch_files` | Optional multiple decks for batch revamp. | Needs max count and result packaging. | ### Translate | Proposed Tool | Description | | --- | --- | | `translate_deck` | Translate decks and office documents while preserving layout and returning the same or selected output format. | Expected inputs: | Parameter | Description | Status | | --- | --- | --- | | `file` | PPTX, Keynote, PDF, Word, or Excel source file. | Needs file reference model. | | `target_language` | Target language. | Needs language code list. | | `source_language` | Optional source language. | Needs auto-detect behavior. | | `glossary_id` | Existing glossary to apply. | Needs glossary model. | | `glossary_terms` | Inline glossary terms for one task. | Needs schema and limits. | | `preserve_layout` | Preserve fonts, sizes, colors, animation, charts, SmartArt, tables, and image text. | Needs default and failure behavior. | | `output_format` | Same as input or explicit format. | Needs enum and defaults. | | `formality` | Tone/formality control if supported. | Needs enum or remove. | ## File Converter Tools The public tools page lists 13 converter tools. MCP can expose them as one grouped tool: | Proposed Tool | Description | | --- | --- | | `convert_file` | Convert one file or text-like source from a supported input format to a target format. | Supported operation candidates: | Operation | Input | Output | | --- | --- | --- | | `html_to_png` | HTML/HTM file or pasted HTML | PNG | | `html_to_pptx` | HTML/HTM file or pasted HTML | PPTX | | `image_to_webp` | Image | WebP | | `keynote_to_html` | Keynote | HTML | | `keynote_to_image` | Keynote | Images | | `keynote_to_pdf` | Keynote | PDF | | `markdown_to_image` | Markdown file or pasted Markdown | Image | | `pdf_to_image` | PDF | Images | | `ppt_to_pptx` | PPT/PPTX | PPTX | | `powerpoint_to_pdf` | PPT/PPTX | PDF | | `powerpoint_to_image` | PPT/PPTX | Images | | `powerpoint_to_video` | PPT/PPTX | MP4 | | `word_to_pdf` | DOC/DOCX | PDF | Parameters to define: | Parameter | Purpose | | --- | --- | | `operation` | Converter operation enum. | | `file` | Uploaded file reference. | | `content` | Pasted HTML or Markdown when no file is used. | | `output_format` | Explicit output type when operation supports more than one. | | `page_range` | Optional page or slide range. | | `render_width` / `render_height` | HTML/image/video rendering size when relevant. | | `scale` | Image rendering density or pixel ratio. | | `include_animations` | Whether PPT to video should preserve basic animations. | | `zip_outputs` | Whether multi-file image outputs should be zipped. | ## Extractor Tools | Proposed Tool | Description | | --- | --- | | `extract_file_content` | Extract OCR text, fonts, or PPTX text shapes from uploaded files. | Supported operation candidates: | Operation | Input | Output | | --- | --- | --- | | `image_ocr` | Image | Text or structured OCR result | | `pptx_font_finder` | PPTX | Font list | | `pptx_text_extractor` | PPTX | Structured text shapes | Parameters to define: | Parameter | Purpose | | --- | --- | | `operation` | Extractor operation enum. | | `file` | Uploaded file reference. | | `languages` | OCR language hints. | | `page_range` | Slides or pages to inspect. | | `include_coordinates` | Return text box coordinates for OCR or PPTX text shapes. | | `include_styles` | Return font family, size, color, and style metadata when available. | | `output_format` | JSON, CSV, TXT, or ZIP if supported. | ## Merger & Splitter Tools | Proposed Tool | Description | | --- | --- | | `compose_files` | Merge, split, or package presentation assets. | Supported operation candidates: | Operation | Input | Output | | --- | --- | --- | | `pptx_merge` | Multiple PPTX files | One PPTX | | `pptx_split` | One PPTX | ZIP of PPTX files | | `html_player_pack` | Multiple HTML files | Playable HTML package | Parameters to define: | Parameter | Purpose | | --- | --- | | `operation` | Merge/split/package operation enum. | | `files` | Ordered file references. | | `slide_ranges` | Ranges to include or split by. | | `preserve_styles` | Whether to preserve source layout, fonts, and theme. | | `canvas_width` / `canvas_height` | HTML player canvas size. | | `title` | Optional HTML player title. | | `description` | Optional HTML player description. | | `output_name` | Desired output filename. | ## Optimizer Tools | Proposed Tool | Description | | --- | --- | | `optimize_file` | Compress, resize, or embed assets in files before delivery. | Supported operation candidates: | Operation | Input | Output | | --- | --- | --- | | `file_compress` | ZIP, PPTX, Keynote, DOCX, XLSX | Compressed file | | `image_resize` | Image | Resized image | | `pptx_embed_fonts` | PPTX plus font choices/files | PPTX | | `video_compress` | Video | Compressed video | Parameters to define: | Parameter | Purpose | | --- | --- | | `operation` | Optimizer operation enum. | | `file` | Uploaded file reference. | | `quality` | Compression quality preset or numeric value. | | `target_size_mb` | Desired maximum output size. | | `width` / `height` | Image resize dimensions. | | `lock_aspect_ratio` | Preserve original image aspect ratio. | | `font_files` | Font files to embed into PPTX. | | `font_names` | Existing font names to embed or subset. | | `video_codec` | Codec selection if supported. | | `video_bitrate` | Bitrate target if supported. | ## Account And Capability Tools | Proposed Tool | Description | | --- | --- | | `get_current_user` | Return authenticated user, workspace, plan, and usage details. | | `get_deckflow_capabilities` | Return supported tools, formats, limits, languages, templates, and feature flags. | | `list_brand_profiles` | List available Brand DNA profiles. | | `list_templates` | List templates available for Create or Revamp. | | `list_glossaries` | List translation glossaries. | | `list_supported_languages` | List supported language codes and names. | These tools reduce hard-coded docs and help agents choose valid parameters at runtime. ## File Size Limits From Current Public Pages | Workflow / Tool | Current Public Limit | | --- | --- | | Translate product workflow | Up to 500 MB | | HTML tools | 50 MB | | Markdown to Image | 10 MB | | Image OCR | 50 MB | | Image to WebP / Image Resizer | 100 MB | | Most deck/document/video tools | 300 MB | Final MCP docs must clarify whether MCP uses the same limits as browser tools, API limits, or plan-specific limits. ---