# Felo 创建演示文稿

POST /api/v1/data/ppts

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

示例使用[总览](https://openapi.felo.ai/zh-CN/docs/data-api/guides/felo-overview.md)中配置的 `FELO_API_KEY`。调用使用**平台余额**，不使用 Felo Pro 积分。响应示例仅展示结构，实际内容和可选字段会变化。





## 1. 创建演示文稿

`POST /api/v1/data/ppts`

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `query` | string | 是 | 生成要求，1–25,000 字符 |
| `stream_protocol` | string | 否 | 默认 `message_center_v1`，通常无需修改 |
| `ppt_config` | object | 否 | 可选配置；当前实现读取 `ai_theme_id` |
| `livedoc_short_id` | string | 否 | 已有上下文 ID，最长 100 字符；需通过原生 API 的归属与有效期检查 |
| `resource_ids` | string[] | 否 | 最多 100 个 UUID 资源 ID，同样受上下文权限检查约束 |

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

```bash
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，标识直接位于根层级：

```json
{
  "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` 等标识。创建成功仅表示任务已接受，不表示生成完成。提示词里的页数是生成要求，计费以实际生成页数为准。

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

### 使用 SSE 读取生成过程

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

```bash
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'
```

| 查询参数 | 说明 |
|---|---|
| `format` | `raw`（默认）保留 `content` 字符串；`structured` 将可解析的 JSON 转为对象或数组 |
| `offset` | 可选的上游恢复位置，用于断线重连；不要自行用事件数量推算 |

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

解析规则和客户端示例与 [SuperAgent 的 SSE 格式](https://openapi.felo.ai/zh-CN/docs/api-reference/superagent.md#2-消费-sse-流)相同，调用时使用本节的 `/api/v1/data/conversations/stream/{stream_key}` 地址。流结束后仍需查询任务结果，导出 PPTX 使用后面的独立流程。此接口不会让 `/api/v1/data/chat` 支持 `stream: true`。



## 有效期、归属与计费

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