themes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: Theme Management

技能：主题管理

Description

描述

Themes define visual styling for slides. This skill documents the public API at

/api/v2/themes

(PublicThemeController). Authenticate with

X-API-KEY

header.

主题定义了幻灯片的视觉样式，本技能文档对应

/api/v2/themes

路径下的公共API（PublicThemeController），通过请求头中的

X-API-KEY

进行鉴权。

TypeScript types (request / response)

TypeScript 类型定义（请求/响应）

Mirrors

PublicThemeController

(/api/v2/themes) data classes.

typescript

// --- List Themes (GET) ---
// Query: offset?: number (default 0), limit?: number (default 20), search?: string
type PublicThemeListResponse = {
  data: PublicThemeResponse[];
  total: number;
  offset: number;
  limit: number;
};

// --- Get Theme By ID (GET) ---
type PublicThemeResponse = {
  id: string;
  name: string;
  description: string | null;
  visibility: string;
  preview_url: string;
  created_at: string;   // ISO 8601
  updated_at: string;   // ISO 8601
};

// --- Generate Theme (POST) — PublicGenerateThemeRequest / PublicGenerateThemeResponse ---
type PublicGenerateThemeRequest = {
  /** Theme generation prompt (required, max 5000 characters) */
  prompt: string;
  /** Optional THEME project ID; if omitted, a project is created automatically */
  project_id?: string;
};

type PublicGenerateThemeResponse = {
  activity_id: string;  // UUID – poll GET /api/v2/jobs/{activityId}
  theme_id: string;     // UUID
};

// --- Apply Theme (POST) — PublicApplyThemeRequest / PublicApplyThemeResponse ---
type PublicApplyThemeRequest = {
  slide_deck_id: string;   // UUID
  theme_id: string;        // UUID
  /** If true, triggers batch image regeneration; poll activity_id when set */
  regenerate_slides?: boolean;  // default false
};

type PublicApplyThemeResponse = {
  theme_id: string;
  theme_name: string;
  slide_deck_id: string;
  applied: boolean;
  activity_id: string | null;  // set when regenerate_slides is true – poll GET /api/v2/jobs/{activityId}
};

与

PublicThemeController

（/api/v2/themes）的数据类完全对齐。

typescript

// --- List Themes (GET) ---
// Query: offset?: number (default 0), limit?: number (default 20), search?: string
type PublicThemeListResponse = {
  data: PublicThemeResponse[];
  total: number;
  offset: number;
  limit: number;
};

// --- Get Theme By ID (GET) ---
type PublicThemeResponse = {
  id: string;
  name: string;
  description: string | null;
  visibility: string;
  preview_url: string;
  created_at: string;   // ISO 8601
  updated_at: string;   // ISO 8601
};

// --- Generate Theme (POST) — PublicGenerateThemeRequest / PublicGenerateThemeResponse ---
type PublicGenerateThemeRequest = {
  /** Theme generation prompt (required, max 5000 characters) */
  prompt: string;
  /** Optional THEME project ID; if omitted, a project is created automatically */
  project_id?: string;
};

type PublicGenerateThemeResponse = {
  activity_id: string;  // UUID – poll GET /api/v2/jobs/{activityId}
  theme_id: string;     // UUID
};

// --- Apply Theme (POST) — PublicApplyThemeRequest / PublicApplyThemeResponse ---
type PublicApplyThemeRequest = {
  slide_deck_id: string;   // UUID
  theme_id: string;        // UUID
  /** If true, triggers batch image regeneration; poll activity_id when set */
  regenerate_slides?: boolean;  // default false
};

type PublicApplyThemeResponse = {
  theme_id: string;
  theme_name: string;
  slide_deck_id: string;
  applied: boolean;
  activity_id: string | null;  // set when regenerate_slides is true – poll GET /api/v2/jobs/{activityId}
};

List Themes

查询主题列表

Query:

offset

(default 0),

limit

(default 20),

search

(optional). Response:

PublicThemeListResponse

bash

curl "$LAYERPROOF_BASE_URL/api/v2/themes?offset=0&limit=20" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY"

查询参数：

offset

（默认0）、

limit

（默认20）、

search

（可选），响应格式为

PublicThemeListResponse

。

bash

curl "$LAYERPROOF_BASE_URL/api/v2/themes?offset=0&limit=20" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY"

Get Theme By ID

根据ID获取主题详情

Response:

PublicThemeResponse

bash

curl "$LAYERPROOF_BASE_URL/api/v2/themes/<theme_id>" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY"

响应格式为

PublicThemeResponse

。

bash

curl "$LAYERPROOF_BASE_URL/api/v2/themes/<theme_id>" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY"

Generate Theme

生成主题

Request body:

PublicGenerateThemeRequest

. Response (202):

PublicGenerateThemeResponse

Only

prompt

is required. Optional

project_id

uses an existing THEME project; if omitted, one is created automatically. Poll

GET /api/v2/jobs/{activityId}

for status.

bash

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/themes/generate" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"prompt":"Clean, minimal style with SF Pro"}'

With optional

project_id

bash

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/themes/generate" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"prompt":"Clean, minimal style","project_id":"<theme_project_uuid>"}'

请求体格式：

PublicGenerateThemeRequest

，响应（202状态码）格式：

PublicGenerateThemeResponse

。仅

prompt

为必填参数，可选

project_id

参数可指定已有主题项目ID，省略则会自动创建新项目。可轮询

GET /api/v2/jobs/{activityId

查询生成状态。

bash

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/themes/generate" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"prompt":"Clean, minimal style with SF Pro"}'

携带可选

project_id

的请求示例：

bash

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/themes/generate" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"prompt":"Clean, minimal style","project_id":"<theme_project_uuid>"}'

Apply Theme

应用主题

Request body:

PublicApplyThemeRequest

. Response:

PublicApplyThemeResponse

Theme and slide deck are specified in the body. When

regenerate_slides

is true, poll

GET /api/v2/jobs/{activityId}

for batch image regeneration status.

bash

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/themes/apply" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"slide_deck_id":"<slide_deck_uuid>","theme_id":"<theme_uuid>"}'

With slide regeneration:

bash

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/themes/apply" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"slide_deck_id":"<slide_deck_uuid>","theme_id":"<theme_uuid>","regenerate_slides":true}'

请求体格式：

PublicApplyThemeRequest

，响应格式：

PublicApplyThemeResponse

。请求体中需要指定主题ID和幻灯片集ID，当

regenerate_slides

设为true时，可轮询

GET /api/v2/jobs/{activityId}

查询批量图片重生成的状态。

bash

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/themes/apply" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"slide_deck_id":"<slide_deck_uuid>","theme_id":"<theme_uuid>"}'

携带幻灯片重生成的请求示例：

bash

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/themes/apply" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $LAYERPROOF_API_KEY" \
  -d '{"slide_deck_id":"<slide_deck_uuid>","theme_id":"<theme_uuid>","regenerate_slides":true}'

Agent behavior

Agent 行为规范

When the user asks to work with themes (list, get, generate, apply), do the following.

当用户要求执行主题相关操作（列表查询、详情获取、生成、应用）时，遵循以下规则：

1. Choose the right endpoint

1. 选择正确的接口

User intent	Endpoint	Method
List/browse themes, search themes	`/api/v2/themes`	GET
Get one theme by ID	`/api/v2/themes/<theme_id>`	GET
Create a new theme from a prompt	`/api/v2/themes/generate`	POST
Apply a theme to a slide deck	`/api/v2/themes/apply`	POST

用户意图	接口路径	请求方法
列出/浏览主题、搜索主题	`/api/v2/themes`	GET
根据ID查询单个主题详情	`/api/v2/themes/<theme_id>`	GET
根据prompt创建新主题	`/api/v2/themes/generate`	POST
为幻灯片集应用主题	`/api/v2/themes/apply`	POST

2. Build and run the request

2. 构建并执行请求

Auth: Every request must include
```
X-API-KEY: $LAYERPROOF_API_KEY
```
. Read
```
LAYERPROOF_BASE_URL
```
and
```
LAYERPROOF_API_KEY
```
from the environment; if missing, tell the user to set them.
GET: Build
```
curl
```
with the chosen path and query params (
```
offset
```
,
```
limit
```
,
```
search
```
for list). Run the curl and show the result.
POST: Build a JSON body from the user's input (prompt, theme ID, slide deck ID, etc.). Use
```
-X POST
```
,
```
-H "Content-Type: application/json"
```
, and
```
-d '...'
```
. Run the curl and show the result.

鉴权：所有请求必须携带
```
X-API-KEY: $LAYERPROOF_API_KEY
```
请求头，从环境变量中读取
```
LAYERPROOF_BASE_URL
```
和
```
LAYERPROOF_API_KEY
```
，如果变量缺失请告知用户进行配置。
GET请求：根据选择的路径和查询参数（列表接口的
```
offset
```
、
```
limit
```
、
```
search
```
）构建curl命令，执行命令并展示结果。
POST请求：根据用户输入（prompt、主题ID、幻灯片集ID等）构建JSON请求体，使用
```
-X POST
```
、
```
-H "Content-Type: application/json"
```
和
```
-d '...'
```
参数构建curl命令，执行命令并展示结果。

3. After generate or apply (with regeneration)

3. 生成主题或开启重生成的应用主题操作后的处理

Generate theme: Response includes
```
activity_id
```
and
```
theme_id
```
. Tell the user the theme was started and give
```
theme_id
```
. Optionally poll
```
GET $LAYERPROOF_BASE_URL/api/v2/jobs/<activity_id>
```
until
```
status
```
is
```
DONE
```
or
```
CANCELED
```
, then report outcome.
Apply theme with
regenerate_slides: true
: Response may include
```
activity_id
```
. If present, tell the user regeneration was started and optionally poll
```
GET .../api/v2/jobs/<activity_id>
```
for status.

生成主题：响应包含
```
activity_id
```
和
```
theme_id
```
，告知用户主题生成任务已启动，并返回
```
theme_id
```
，可选轮询
```
GET $LAYERPROOF_BASE_URL/api/v2/jobs/<activity_id>
```
直到状态变为
```
DONE
```
或
```
CANCELED
```
，再反馈最终结果。
开启
regenerate_slides: true
的应用主题操作：响应可能包含
```
activity_id
```
，如果存在则告知用户重生成任务已启动，可选轮询
```
GET .../api/v2/jobs/<activity_id
```
查询状态。

4. Response handling

4. 响应处理规则

Always show the raw JSON response in a JSON code block; do not convert to a table.
If the response contains a URL for an image (e.g.
```
preview_url
```
), show the image and the JSON.
On error (4xx/5xx), show the response body and status code; suggest fixing missing/invalid API key, IDs, or request body.

始终将原始JSON响应放在JSON代码块中展示，不要转换为表格。
如果响应中包含图片URL（例如
```
preview_url
```
），需要同时展示图片和JSON响应。
遇到错误（4xx/5xx状态码）时，展示响应体和状态码，建议用户检查API key、ID是否缺失/无效，或者请求体是否正确。

5. Example workflows

5. 示例工作流

Workflow A — User: "Generate a theme with prompt: minimal dark mode."

Choose
```
POST /api/v2/themes/generate
```
.
Build body:
```
{"prompt":"minimal dark mode"}
```
.

Run:

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/themes/generate" -H "Content-Type: application/json" -H "X-API-KEY: $LAYERPROOF_API_KEY" -d '{"prompt":"minimal dark mode"}'

Show the JSON response; if it contains
```
activity_id
```
, mention they can poll
```
/api/v2/jobs/{activityId}
```
for status and use
```
theme_id
```
once done.

Workflow B — User: "List themes, generate a new 'corporate blue' theme, wait for it to finish, then apply it to my slide deck and regenerate slides."

GET
```
/api/v2/themes
```
with optional
```
limit
```
,
```
offset
```
,
```
search
```
; show list. User may pick existing or request new.

POST

/api/v2/themes/generate

with

{"prompt":"corporate blue"}

; capture

activity_id

and

theme_id

Poll
```
GET /api/v2/jobs/{activity_id}
```
until status is DONE (or CANCELED). If DONE, theme is ready; if failed, report
```
failure_reason
```
.
Resolve projectId and slideDeckId (projects + slide-deck). POST or PUT the slide-deck theme/settings endpoint with
```
theme_id
```
(e.g. PUT
```
.../slide-deck/.../settings
```
with
```
{"theme_id":"<theme_id>"}
```
).
If the API supports "apply theme and regenerate": use that endpoint with
```
regenerate_slides: true
```
; capture
```
activity_id
```
and poll jobs until DONE. Otherwise: apply theme then use slide-deck batch-generate; poll that job.

Workflow C — User: "I have a theme ID; apply it to deck X and only update the look (no slide regeneration)."

Resolve slideDeckId from project. PUT
```
.../settings
```
with
```
{"theme_id":"<theme_id>"}
```
(or apply-theme without regeneration).
Confirm with GET deck;
```
slide_deck.theme
```
or similar should reflect the new theme. No job polling needed if no regeneration.

工作流A — 用户需求："生成一个主题，prompt是：极简深色模式"

选择
```
POST /api/v2/themes/generate
```
接口。
构建请求体：
```
{"prompt":"minimal dark mode"}
```
。

执行命令：

curl -X POST "$LAYERPROOF_BASE_URL/api/v2/themes/generate" -H "Content-Type: application/json" -H "X-API-KEY: $LAYERPROOF_API_KEY" -d '{"prompt":"minimal dark mode"}'

。

展示JSON响应，如果包含
```
activity_id
```
，告知用户可以轮询
```
/api/v2/jobs/{activityId}
```
查询状态，生成完成后即可使用对应的
```
theme_id
```
。

工作流B — 用户需求："列出所有主题，生成一个新的'企业蓝'主题，等待生成完成后应用到我的幻灯片集，并重生成幻灯片。"

调用GET
```
/api/v2/themes
```
接口，携带可选的
```
limit
```
、
```
offset
```
、
```
search
```
参数，展示主题列表，用户可以选择现有主题或要求生成新主题。

调用POST

/api/v2/themes/generate

接口，请求体为

{"prompt":"corporate blue"}

，获取

activity_id

和

theme_id

。

轮询
```
GET /api/v2/jobs/{activity_id}
```
直到状态变为DONE或CANCELED，如果状态为DONE则主题已就绪，如果失败则返回
```
failure_reason
```
。
解析projectId和slideDeckId（项目+幻灯片集），调用幻灯片集主题/配置接口设置
```
theme_id
```
（例如调用PUT
```
.../slide-deck/.../settings
```
，请求体为
```
{"theme_id":"<theme_id>"}
```
）。
如果API支持"应用主题并重生成"功能：使用对应接口并设置
```
regenerate_slides: true
```
，获取
```
activity_id
```
后轮询任务状态直到完成，否则先应用主题再调用幻灯片集批量生成接口，轮询对应任务状态。

工作流C — 用户需求："我有一个主题ID，把它应用到幻灯片集X，只更新样式不要重生成幻灯片。"

从项目中解析slideDeckId，调用PUT
```
.../settings
```
接口，请求体为
```
{"theme_id":"<theme_id>"}
```
（或者调用不带重生成参数的应用主题接口）。
调用GET接口查询幻灯片集信息确认结果，
```
slide_deck.theme
```
或类似字段应该已经更新为新主题，没有开启重生成则不需要轮询任务状态。

Response format (required)

响应格式要求（强制）

(if response contains url to show image) please show image and show json response instead of table
Always show the raw JSON response (verbatim) in a JSON code block.
If the response contains a URL for an image, render/show the image and also show the JSON response (do not convert to a table).

如果响应中包含需要展示的图片URL，请同时展示图片和JSON响应，不要转换为表格。
始终将原始JSON响应原样放在JSON代码块中展示。
如果响应中包含图片URL，渲染/展示图片的同时也要展示JSON响应（不要转换为表格）。