Felo API (harness)

PPT Task API

创建 PPT 生成任务、列出主题，并轮询共享任务 endpoints。

POST/v2/ppts

认证

Bearer API key

Content type

application/json

限流说明

可能适用 endpoint 专属限制。

LiveDoc API Landing Page Task API

PPT Task API 提供异步 PPT 生成能力。你可以创建 task，然后通过 task_id 轮询状态；也可以浏览可用 PPT themes 并在创建任务时应用。

认证

Authorization: Bearer YOUR_API_KEY

1. 列出 PPT 主题

GET https://openapi.felo.ai/v2/ppt-themes

参数	类型	必填	说明
`lang`	string	否	本地化内容语言，例如 `en`、`zh-Hans`，默认 `en`
`type`	string	否	按 theme type 过滤
`keyword`	string	否	搜索关键词，匹配 theme title
`page`	integer	否	页码，从 1 开始
`size`	integer	否	每页数量，最大 100

2. 创建 PPT 任务

POST https://openapi.felo.ai/v2/ppts

请求支持两种 Content-Type：

application/json：通过 prompt 创建任务，可使用已有 LiveDoc resources 作为上下文。
multipart/form-data：上传一个文件，并基于该文件直接创建 PPT 任务。

JSON 请求

参数	类型	必填	说明
`query`	string	是	PPT 生成请求 prompt
`livedoc_short_id`	string	否	关联已有 LiveDoc；省略时会自动创建新 LiveDoc
`resource_ids`	array of strings	否	用作 PPT 生成上下文的 LiveDoc 资源 ID
`ppt_config`	object	否	PPT 配置项
`ppt_config.ai_theme_id`	string	否	来自列出 PPT 主题的 Theme ID

curl -X POST 'https://openapi.felo.ai/v2/ppts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"query":"Felo，生成 2 页 PPT"}'

上传文件创建 PPT

使用 multipart/form-data 可在一次请求中上传一个文件并创建 PPT 任务。平台会先将文件上传为 LiveDoc resource，再把对应的 resource ID 传给 PPT 任务。

Part	类型	必填	说明
`query`	string	是	PPT 生成请求 prompt
`file`	file	是	用作 PPT 上下文的源文件
`stream_protocol`	string	否	流式协议，默认 `message_center_v1`
`livedoc_short_id`	string	否	接收文件的已有 LiveDoc；省略时自动创建新 LiveDoc
`ppt_config`	JSON	否	与 JSON 请求体结构相同的 PPT 配置；该 part 请使用 `application/json` 类型

curl -X POST 'https://openapi.felo.ai/v2/ppts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'query=基于这份报告生成 10 页演示文稿' \
  -F 'ppt_config={"ai_theme_id":"02968979-a69f-42c4-b136-de02c40ab2d7"};type=application/json' \
  -F '[email protected]'

响应结构与 JSON 请求一致。返回的 livedoc_short_id 对应保存上传资源的 LiveDoc。

成功响应包含 livedoc_short_id、ppt_business_id 和 task_id。

3. Query Task Status

GET https://openapi.felo.ai/v2/tasks/{task_id}/status

4. Query Task Historical Info

GET https://openapi.felo.ai/v2/tasks/{task_id}/historical

完成后可能返回 ppt_url、live_doc_short_id、live_doc_url 或 ai_page_html。

5. 导出 PPTX

先等待 PPT 生成任务达到 COMPLETED，使用创建任务返回的 ppt_business_id（或历史信息中的 ppt_biz_id）提交导出。导出是异步操作。

POST https://openapi.felo.ai/v2/ppts/{ppt_business_id}/export
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请求体可使用空对象 {}。该 API Key 对应的用户必须拥有此 PPT。重复提交正在处理的导出不会新建任务；导出成功后再次提交会重新生成 PPTX。

curl -X POST 'https://openapi.felo.ai/v2/ppts/YOUR_PPT_BUSINESS_ID/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

使用以下接口查询结果；建议每 2–5 秒查询一次，直到状态为 COMPLETED 或 FAILED：

GET https://openapi.felo.ai/v2/ppts/{ppt_business_id}/export
Authorization: Bearer YOUR_API_KEY

导出完成的响应示例：

{
  "status": "ok",
  "message": null,
  "data": {
    "status": "COMPLETED",
    "download_url": "https://example.com/presentation.pptx?signature=...",
    "expires_at": "2026-09-29T10:30:00Z"
  }
}

status 可为 NOT_STARTED、PROCESSING、COMPLETED 或 FAILED。只有 COMPLETED 时才返回 download_url 和 expires_at。下载链接自签发起 30 分钟有效；过期后再次调用查询接口可取得新链接。查询接口不会重新生成 PPTX。

每次新导出按现有 PPT 导出积分规则计费；积分不足时返回 HTTP 402。导出 endpoint 可能适用专属限流；如收到 HTTP 429，请按响应提示稍后重试。导出失败后可重新提交。

说明

PPT generation 是异步任务，创建后需要轮询 status 或 historical endpoint。
如果请求包含 LiveDoc resources，生成内容会结合这些资源。
如果任务失败，请保存 task_id 并联系 support。