Beautiful.ai 快速上手：用结构化大纲通过 API 生成演示文稿

Beautiful.ai 提供了一套 HTTP API，其中 /createPresentation 接口可以把调用方准备好的结构化大纲直接转成一份演示文稿。它适合这样的场景：内容已经在别的系统里生成或整理好了（例如从文档、数据库、模板引擎里产出的章节与要点），需要批量、可重复地变成排版好的幻灯片，而不是在网页编辑器里一张张手工搭。本文按接口文档整理出一条从零到跑通的路径，重点讲清请求体里每个字段的作用、必填与可选的边界，以及一个最小可用的完整示例。如果你更习惯在网页端直接操作，可以先看站内的 Beautiful.ai 工具页了解产品形态，再回到本文处理接口调用。

准备工作

账号与权限

调用接口前需要有一个可用的 Beautiful.ai 账号，并且该账号具备创建演示文稿的权限。接口返回 403 表示身份验证通过但当前账号不被允许执行该操作，这通常与工作区权限或套餐能力有关，遇到时先确认账号在目标工作区里是否有创建权限。

API 密钥

接口使用 API 密钥鉴权，密钥放在请求头中随请求发送。文档中的示例按语言（Shell、Node、Ruby、PHP、Python）分别给出了请求头写法，核心是同一个鉴权头。密钥属于敏感凭据，不要写进前端代码或提交到代码仓库，放在服务端环境变量里读取。

接口地址与版本

接口的基础地址是 https://www.beautiful.ai/api/v1，创建演示文稿的路径为 /createPresentation，请求方法为 POST。当前文档标注的版本为 v1.0。

先摸清可用的资源 ID

请求体里的 folderId、themeId、workspaceId 都是可选字段，但一旦要指定，就必须填真实存在的 ID。这些 ID 不是猜出来的，而是通过配套的查询接口获得：

• GET /getFolders：列出可用文件夹，返回的文件夹 ID 可直接用于 folderId。
• GET /getThemes：列出可用主题，返回的主题 ID 可直接用于 themeId。
• POST /listPresentations：列出当前可访问的演示文稿，可用于核对创建结果。
• POST /getPresentation：加载一份已有演示文稿，用于检查生成后的实际内容。

建议在正式写创建逻辑之前，先用这几个接口把目标工作区里的文件夹与主题列一遍，把要用的 ID 记下来。这样后面调试创建请求时，就不会因为一个无效 ID 反复排查。

操作步骤

第一步：确定请求体结构

/createPresentation 的请求体是一个 JSON 对象，字段分为三类：定位类（工作区、文件夹）、样式类（主题、图片、语言）、内容类（标题与幻灯片数组）。逐项说明如下。

字段	类型	是否必填	说明
title	string	必填	演示文稿标题。
slides	对象数组	必填	幻灯片内容，长度至少为 1，即不能为空数组。
workspaceId	string	可选	显式指定目标工作区。
folderId	string	可选	演示文稿要放入的文件夹，取值来自 /getFolders。
themeId	string	可选	使用的主题，取值来自 /getThemes。
themeOptions	object	可选	主题相关的细化选项，见下一节。
language	string	可选	生成内容所使用的语言。
preserveExactText	boolean	可选	取 true 或 false，控制是否原样保留文本。

两个必填项里，slides 是最容易出错的地方：它必须是数组，且至少包含一个元素。传空数组会直接导致请求不合法。

第二步：配置主题选项

themeOptions 是一个对象，文档中列出的子字段包括：

• imageSource：字符串枚举，允许的值为 ai、web、stock、none，用于决定幻灯片配图的来源。
• imageStyle：字符串，用于指定配图风格。

其中 imageSource 的四个取值含义比较直观：ai 走 AI 生成，web 走网络图片，stock 走图库，none 表示不使用图片。如果内容本身以文字和图表为主，把 imageSource 设为 none 可以避免生成无关配图；如果希望每页都有视觉元素，再按需要选择前三种之一。注意这个字段是枚举，传了列表之外的值会被判为请求不合法。

第三步：组织幻灯片数组

slides 是一个对象数组，每个元素代表一页幻灯片。文档中该字段的类型标注为 slides * ADD object，即数组元素为对象，且至少一项。实际组织时，建议把每一页拆成「这一页要讲什么」的结构化描述，而不是把整段长文塞进一个字段——接口的定位就是从结构化大纲生成演示文稿，输入越结构化，输出越接近预期。

一个实用的做法是先在本地把大纲整理成数组，每个元素对应一个章节或一个论点，再整体序列化进请求体。这样既方便在代码里复用，也方便在出错时定位是哪一页的数据有问题。

第四步：发送请求

用 curl 发送请求的最小形态如下。把 YOUR_API_KEY 换成自己的密钥，请求体按上一步的结构填写：

curl -X POST 'https://www.beautiful.ai/api/v1/createPresentation' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "title": "季度业务回顾",
    "slides": [
      { "title": "本季度概览" },
      { "title": "关键指标" }
    ]
  }'

如果使用 Node、Python、Ruby 或 PHP，文档为每种语言都给出了对应的示例片段，逻辑一致：设置 JSON 内容类型、带上鉴权头、以 POST 提交请求体。选自己项目里已有的 HTTP 客户端即可，不必额外引入 SDK。

第五步：读取响应

接口返回 200 表示演示文稿创建成功。文档在响应区提供了 application/json 的 200 示例以及 400、401、403、500 的示例，可以在文档页的 Try It 面板里直接发起请求查看实际返回。创建成功后，可以用 POST /listPresentations 列出可访问的演示文稿来确认新文档已经出现，再用 POST /getPresentation 加载它检查内容。

一个完整示例

下面是一个从头到尾可跑通的最小流程：先查主题，再创建演示文稿，最后核对结果。示例中的 ID 均为占位，需要替换成自己账号下真实返回的值。

1. 查询可用主题

curl -X GET 'https://www.beautiful.ai/api/v1/getThemes' \
  -H 'Authorization: Bearer YOUR_API_KEY'

从返回结果里挑一个主题，记下它的 ID。

2. 查询可用文件夹

curl -X GET 'https://www.beautiful.ai/api/v1/getFolders' \
  -H 'Authorization: Bearer YOUR_API_KEY'

同样记下目标文件夹的 ID。如果不需要归档到特定文件夹，这一步可以跳过，创建时不传 folderId 即可。

3. 创建演示文稿

curl -X POST 'https://www.beautiful.ai/api/v1/createPresentation' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "title": "产品发布计划",
    "themeId": "THEME_ID_FROM_GETTHEMES",
    "folderId": "FOLDER_ID_FROM_GETFOLDERS",
    "language": "zh-CN",
    "preserveExactText": true,
    "themeOptions": {
      "imageSource": "stock",
      "imageStyle": "minimal"
    },
    "slides": [
      { "title": "背景与目标" },
      { "title": "目标用户与场景" },
      { "title": "功能范围" },
      { "title": "上线节奏" },
      { "title": "风险与应对" }
    ]
  }'

这个请求覆盖了所有可选字段的典型用法：指定主题、指定文件夹、指定语言、要求原样保留文本、指定配图来源与风格，并给出五页的大纲。实际使用时可以按需删减，只保留 title 与 slides 也能成功创建。

4. 核对结果

curl -X POST 'https://www.beautiful.ai/api/v1/listPresentations' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{}'

在返回列表中找到刚创建的「产品发布计划」，拿到它的标识后，再用 POST /getPresentation 加载详情，逐页检查排版与文字是否符合预期。如果某些页面的文本被改写或截断，回头调整 preserveExactText 与大纲的粒度。

注意事项

错误码的含义

接口文档明确列出了五种响应状态，排查时按这个顺序对照即可：

• 200：演示文稿创建成功。
• 400：请求不合法。常见原因是缺少 title、slides 为空数组、imageSource 传了枚举之外的值，或 folderId、themeId 不是有效 ID。
• 401：API 密钥缺失或无效。检查鉴权头是否带上、密钥是否过期。
• 403：身份验证通过，但不允许执行该操作。检查账号在目标工作区中的权限。
• 500：服务端内部错误。这类错误与请求内容无关，重试或稍后再试。

必填与可选的边界

只有 title 和 slides 是必填的，其余字段全部可选。这意味着一个只带标题和一页幻灯片的最小请求是合法的。反过来说，任何可选字段一旦出现，就必须符合类型与取值约束：slides 长度不得小于 1，imageSource 只能取 ai、web、stock、none，preserveExactText 只能是布尔值。

ID 必须来自查询接口

workspaceId、folderId、themeId 都不是自由填写的字符串。文件夹 ID 来自 /getFolders，主题 ID 来自 /getThemes。跨工作区复用 ID 往往会导致 400 或 403，切换工作区时记得重新查询。

相关接口的用途

除了本文重点讲的 /createPresentation，同一套 API 还提供几个相邻能力，按需组合使用：

• /createPresentationFromTemplate：复制一份演示文稿模板并插值变量，适合已有固定版式的场景。配合 /getPresentationTemplateVariables 可以先查看模板里有哪些变量可填。
• /generatePresentation：从一段提示词生成演示文稿，适合没有现成大纲、只有想法的情况。
• /exportPresentation：导出演示文稿。
• /listPresentationTemplates：列出可访问的演示文稿模板。

选择哪条路径取决于输入形态：有结构化大纲用 /createPresentation，有固定模板用 /createPresentationFromTemplate，只有一句话需求用 /generatePresentation。

以官方当前信息为准

接口的字段、枚举取值、可用主题与文件夹、套餐能力都可能随版本调整，本文所述以文档 v1.0 为准。正式接入前请核对官网当前的接口说明与账号套餐，价格与配额同样以官网当前信息为准。