快速开始 - DeckFlow 开发者

DeckFlow API 采用异步任务模型处理大多数文件操作，支持多种文档与演示文稿的翻译、焕新和生成。

核心步骤

步骤 1：获取并配置 API 密钥

在开始之前，请登录 DeckFlow，在设置页面生成您的 API 密钥（API Key）。

配置环境变量以开始使用：

# 配置 API 密钥和基础路径
export DECKFLOW_API_KEY="Bearer <YOUR_API_KEY>"
export DECKFLOW_API_BASE="https://app.deckflow.com/api"

详细说明请参阅 API 密钥。

步骤 2：提交任务

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

请求路径：POST /tools/tasks
请求头：
Authorization: Bearer <YOUR_API_KEY>
Content-Type: multipart/form-data
主要参数：
files：本地文件。
type：任务类型，例如 translation。
params：JSON 字符串。例如 {"from":"zh","to":"en"}。

以下为提交翻译任务的代码示例：

  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\"}"'

  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);

  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（失败）。

  curl -X GET "$DECKFLOW_API_BASE/tools/tasks/YOUR_TASK_ID" \
    -H "Authorization: $DECKFLOW_API_KEY"

  // 简易轮询函数
  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 秒后重试
    }
  }

  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 请求。

  curl -X GET "$DECKFLOW_API_BASE/tools/tasks/YOUR_TASK_ID" \
    -H "Authorization: $DECKFLOW_API_KEY" \
    -H "response-event-stream: yes"

  // 在 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;
        }
      }
    }
  }

  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 获取已处理文件的临时签名下载链接，并将文件下载保存至您的本地。

临时签名 URL 具有有效期限制。如需长久保存处理完成的文件，请务必在链接过期前将文件下载并转存到您自己的存储服务或数据库中。