PPT 生成与导出

异步生成演示文稿，再导出 PPTX 文件。创建任务成功与文件生成完成是两个阶段，需要分别处理。

示例使用总览中配置的 FELO_API_KEY。调用使用平台余额，不使用 Felo Pro 积分。响应示例仅展示结构，实际内容和可选字段会变化。

完整流程与标识

1. 创建生成任务，保存 task_id、ppt_business_id 和 expires_at。
2. 使用 task_id 轮询生成状态。
3. 使用 task_id 读取生成结果。
4. 使用 ppt_business_id 发起 PPTX 导出。
5. 查询导出状态，完成后下载文件。
6. 按需提前删除演示文稿。

路径中的 {business_id} 指返回的 `ppt_business_id`，不是 task_id、resource_id 或 livedoc_short_id。全流程使用同一个 API 账户。下面示例中的 ID 都需要替换为真实返回值。

1. 创建演示文稿

POST /api/v1/data/ppts

首次接入建议不传上下文和配置字段。通过 /v2 创建的上下文，不代表可以直接在此复用。

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/ppts" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"面向软件开发者，生成一份介绍检索增强生成的 5 页中文演示文稿。"}'

HTTP 200，标识直接位于根层级：

{
  "task_id":"example-task-id",
  "ppt_business_id":"example-ppt-id",
  "livedoc_short_id":"example-livedoc-id",
  "expires_at":"2026-11-13T00:00:00Z"
}

可能还会返回 resource_id、stream_key、thread_short_id 等标识。创建成功仅表示任务已接受，不表示生成完成。提示词里的页数是生成要求，计费以实际生成页数为准。

TASK_ID="example-task-id"
PPT_ID="example-ppt-id"

使用 SSE 读取生成过程

如果创建响应返回 stream_key，可以使用同一账户的 API Key 立即连接原生流接口。没有 stream_key 时，继续使用下面的任务状态和结果查询流程。

curl -N 'https://openapi.felo.ai/api/v1/data/conversations/stream/YOUR_STREAM_KEY?format=structured' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: text/event-stream'

读取完整 SSE 事件后解析外层 JSON，再处理 content。业务事件 answer 的文本位于 data.text，finished 表示流中的生成过程完成；同时处理上游可能发送的 done、[DONE] 和 error。无完成信号就断线时，先查询任务状态。

解析规则和客户端示例与 SuperAgent 的 SSE 格式相同，调用时使用本节的 /api/v1/data/conversations/stream/{stream_key} 地址。流结束后仍需查询任务结果，导出 PPTX 使用后面的独立流程。此接口不会让 /api/v1/data/chat 支持 stream: true。

2. 查询生成状态

GET /api/v1/data/tasks/{task_id}/status

curl -sS --request GET "https://openapi.felo.ai/api/v1/data/tasks/$TASK_ID/status" \
  -H "Authorization: Bearer $FELO_API_KEY"

返回根层级的 status 字符串，例如 RUNNING 或 COMPLETED。建议每隔 2–5 秒查询一次，并设置最长等待时间。完成后再读取结果；失败或遇到未识别状态时，不要直接视为成功。客户端停止轮询不会取消任务。

{"status":"COMPLETED"}

3. 获取生成结果

POST /api/v1/data/tasks/{task_id}/historical

注意这里是 POST，无需 JSON 请求体。

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/tasks/$TASK_ID/historical" \
  -H "Authorization: Bearer $FELO_API_KEY"

{
  "task_id":"example-task-id",
  "task_status":"COMPLETED",
  "history_data":{},
  "error_message":null
}

先判断 task_status，再使用 history_data。历史内容会随任务变化，也可能为空。ai_page_html、thread_short_id 是可选字段。此接口不保证直接返回 PPTX 下载地址，下载文件需要下一步导出。

4. 发起 PPTX 导出

POST /api/v1/data/ppts/{business_id}/export

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/ppts/$PPT_ID/export" \
  -H "Authorization: Bearer $FELO_API_KEY"

{"status":"PROCESSING","download_url":null,"expires_at":null}

请先确认生成完成。同一导出进行中，重复 POST 会复用该任务；导出完成后再次 POST 会新建导出，可能再次计费。查询状态和刷新下载链接都应使用 GET。

5. 查询导出状态并下载

GET /api/v1/data/ppts/{business_id}/export

curl -sS --request GET "https://openapi.felo.ai/api/v1/data/ppts/$PPT_ID/export" \
  -H "Authorization: Bearer $FELO_API_KEY"

{
  "status":"COMPLETED",
  "download_url":"https://example.com/presentation.pptx?signature=example",
  "expires_at":"2026-11-06T00:30:00Z"
}

示例地址仅展示结构，请使用真实返回的签名链接。下载链接有效期为 30 分钟；只要演示文稿仍有效，GET 查询导出状态即可获取新的链接。请及时保存文件，不要把 Felo API Key 发送给文件下载域名。

6. 删除演示文稿

DELETE /api/v1/data/ppts/{business_id}

curl -sS --request DELETE "https://openapi.felo.ai/api/v1/data/ppts/$PPT_ID" \
  -H "Authorization: Bearer $FELO_API_KEY"

成功返回 HTTP 204，响应体为空，不要继续解析 JSON。生成尚未结束时删除会返回 409。

有效期、归属与计费

• 演示文稿在创建七天后过期，查询和导出不会延长有效期。创建响应和导出响应中的 expires_at 分别表示文稿到期时间与下载链接到期时间。
• 只能访问当前 API 账户创建的任务和文稿。资源不存在或无权访问可能返回 404；过期或已删除可能返回 410，清理后也可能返回 404。
• 生成按实际页数计费（ppt.generate）。按页定价时，创建先预留十页费用，生成成功后按实际产出结算并释放未使用部分。即使提示词只要求五页，提交时仍需满足预留额度。
• 导出单独按请求计费（ppt.export）。生成状态、生成结果、导出状态查询以及删除均不新增费用。
• 遇到超时，优先查询已保存的任务，不要立即再创建一份。详见计费与错误处理。