使用 Sleek 进行设计

概述

sleek.design 是一种由AI驱动的移动应用设计工具。您通过 REST API（路径为 /api/v1/*）与之交互，以创建项目、用自然语言描述您想要构建的内容，并获取渲染后的界面。所有通信均使用标准HTTP，并通过Bearer令牌进行身份验证。

基础URL: https://sleek.design 身份验证: 每个 /api/v1/* 请求均需包含 Authorization: Bearer $SLEEK_API_KEY Content-Type: application/json（请求与响应） CORS: 所有 /api/v1/* 端点均启用CORS 解析响应: 将响应体写入文件（curl -o run.json）并解析该文件。不要通过 echo 管道传输JSON：在zsh中，它会将字符串值中的转义 \n 展开为实际换行符，从而使响应体变为无效JSON。 API文档: 位于 https://sleek.design/api/v1/spec.json 的OpenAPI规范；可浏览的文档位于 https://sleek.design/api/v1/docs。如需本指南未涵盖的合同细节，请获取该规范。

前提条件：API密钥

如果 SLEEK_API_KEY 未设置，请使用设备流，这样用户永远不会直接处理原始密钥：

POST https://sleek.design/api/v1/device/start（无需身份验证），请求体为 {"source": "your-tool-slug"}。响应包含一个 verificationUrl、一个人类可检查的 userCode、一个保密的 deviceCode 以及轮询 interval（以秒为单位）。
向用户展示 verificationUrl 和 userCode，并告知他们确认代码匹配后再批准。
每 interval 秒轮询 POST https://sleek.design/api/v1/device/poll，请求体为 {"deviceCode": "..."}。当用户批准时，轮询会恰好返回一次 {"status": "approved", "key": "sk_..."}：将其存储为 SLEEK_API_KEY。代码在15分钟后过期；如果过期，则重新开始。

备用方案：将用户引导至 **https://sleek.design/agents/setup**，该页面在一个地方处理登录、计划升级和密钥创建，并要求他们将密钥粘贴回给您。密钥也可以在 https://sleek.design/dashboard/api-keys 进行管理。完整密钥值仅在创建时显示一次。

计划: 免费账户可以使用一次性试用积分（大约一次设计运行）来试用API，因此新用户可以在任何支付决策之前看到他们的第一个设计。持续使用需要Pro计划或更高版本（每月49.99美元，或按年计费每月30美元，每年360美元；包括每月20,000个AI积分，大约650个界面）。当成本变得相关时（用户询问、需要升级才能继续，或者您即将将他们引导至支付页面），请清晰地说明此定价，包括按年选项。绝不要让支付步骤出乎意料。

密钥作用域

作用域	解锁的功能
`projects:read`	列出/获取项目
`projects:write`	创建/删除项目
`components:read`	列出项目中的组件
`chats:read`	获取聊天运行状态
`chats:write`	发送聊天消息
`screenshots`	渲染组件截图

仅为任务所需的作用域创建密钥。

安全与隐私

单一主机: 所有请求仅发送至 https://sleek.design。不会向第三方发送任何数据。
仅HTTPS: 所有通信均使用HTTPS。API密钥仅在 Authorization 标头中传输至Sleek端点。
最小作用域: 仅创建任务所需作用域的API密钥。优先使用短期或可撤销的密钥。
图像URL: 在聊天消息中使用 imageUrls 时，这些URL将由Sleek的服务器获取。避免传递包含敏感内容的URL。

设计

以下使用的每个端点的完整请求/响应形式均在API参考中。

1. 创建项目

如果项目尚不存在，请使用 POST /api/v1/projects 创建项目。根据请求内容派生项目名称。

每个项目都有自己的主题、样式和设计系统。如果用户想要多种设计变体，请为每个变体创建一个单独的项目。

2. 发送聊天消息

使用 POST /api/v1/projects/:id/chat/messages 发送请求。Sleek会根据您的消息规划界面内容和布局，如果您未指定视觉样式，它将自行设计。不要将请求分解为单独的界面，也不要添加用户未要求的产品细节；将完整意图作为一条消息发送。如果用户描述了特定界面，请包含这些信息。Sleek在拥有足够规划空间时能生成更丰富的设计。

编写风格指导: 每当用户为您提供了任何可依据的内容时（参考图像、他们喜欢的应用、氛围形容词、需要避免的事项），或者当您要生成多个变体时（每个变体一个方向），请编写一个风格指导。仅在请求非常简洁时才原样传递请求。风格指导是一条包含在消息中的综合性段落，涵盖氛围（2-3个形容词）、色彩策略（逻辑而非十六进制代码）、排版感觉、布局理念、组件样式（圆角、边框与阴影、导航处理）、图像和插画风格，以及一到两个独特细节。要确定调色板、字体方向和整体感觉——任何仅设定氛围的内容读起来都像提示而非指导。要有主见；不要含糊其辞。将个性放在颜色、字体和图像中，而不是放在不寻常的布局或导航中。

扩展用户提供的内容，永远不要与之矛盾。当他们指向参考图像或他们喜欢的应用时，研究每一个，并将您从中获取的内容融入指导——Sleek只能看到作为 imageUrls 传递的图像，因此对于本地内容，指导是这些参考如何到达Sleek的途径。借鉴模式，切勿借用来源方的品牌信息、内容或名称。

使用风格指导或 referenceId，但不能同时使用——参考本身已包含完整的风格指南。

使用参考植入风格: Sleek精选了一个设计参考目录。当用户想要特定外观或请求样式选项时，使用 GET /api/v1/references 列出它们（每个都有 name 和您可以显示的 previewImageUrls），并将所选id作为 referenceId 传递到项目的第一条消息中，以便其风格指南植入整个设计。

标识您的工具: 始终发送 source，即发出请求的工具的slug。Sleek编辑器使用它来在运行流式传输时向用户显示谁在设计。已识别的值：claude-code、claude、codex、chatgpt、cursor、openclaw、grok。如果您的工具未列出，无论如何请发送一个简短的kebab-case slug（最多64个字符）。无法识别的值也没问题，会获得通用标签。

实时观看: 运行会在Sleek编辑器中实时渲染。在向项目发送第一条消息后，告诉用户他们可以在Sleek中实时观看界面设计，并分享编辑器链接：https://sleek.design/project/:projectId。除非用户要求，否则不要自行打开浏览器。

轮询: 聊天消息默认是异步的：您会得到一个 runId，并轮询 GET /api/v1/projects/:id/chat/runs/:runId。从2秒间隔开始，10秒后回退到5秒，5分钟后放弃。在 completed 或 failed 时退出；如果您无法读取状态，请停止并报告，而不是将其计为“尚未完成”。您也可以使用 ?wait=true 进行阻塞调用（最多300秒；如果超时返回 202，则回退到轮询）。

编辑特定界面: 使用 target.screenId 将更改定向到正确的界面。screenId 来自运行的 result.operations 或 GET /api/v1/projects/:id/components 返回的每个组件上的 screenId 字段；它不是组件ID。

一次一个运行: 每个项目只允许一个活动运行。如果您收到 409 CONFLICT，请等待当前运行完成后再发送下一条消息。如果用户改变了主意或旧运行阻塞了项目，请取消它（参见取消运行）。不同项目的消息可以并行运行；并行运行多个项目时，请使用异步轮询（而非 ?wait=true）。

安全重试: 添加一个 idempotency-key 标头（≤255个字符）以实现重试安全重新发送。服务器会返回现有运行，而不是创建重复运行。

3. 显示结果

在每个产生 screen_created 或 screen_updated 操作的聊天运行之后，截取屏幕截图并向用户展示，使用 POST /api/v1/screenshots。仅在用户看到了运行创建或更新的每个界面的屏幕截图后，步骤才算完成；切勿静默完成一个运行。

新界面: 每个界面一个截图 + 项目所有界面的一个组合截图。
更新的界面: 每个受影响的界面一个截图。

除非用户明确请求特定的背景色，否则使用 background: "transparent"。

将截图保存在项目目录（而非临时文件夹）中，以便用户轻松查看。

展示与审查: 默认设置仅捕获视口，这对用户来说是合适的框架——界面看起来像手机屏幕。但它们不适合判断您自己的工作，因为折叠下方的内容会被裁剪掉。当您审查运行产生的内容时，使用 fullHeight: true 重新截取界面（每个请求一个界面），以查看整个可滚动页面。

截图请求是独立的，因此请并行发送它们——面向用户的截图和您的 fullHeight 审查截图一起发出，不同界面的截图也一样。“每个请求一个界面”支配每个图像中包含的内容，而不是您发送它们的速度；这不是等待一个响应再开始下一个的理由。只有在实际收到 429 时才回退。

切勿仅从视口截图判断界面不完整。 看起来缺失的内容几乎总是位于折叠下方。在告知用户某些内容缺失，或发送后续消息请求Sleek添加它之前，请通过整个界面进行确认：使用 fullHeight: true 截图，或通过 GET /api/v1/projects/:id/components/:componentId 获取组件HTML（这是界面内容的真实来源）。截图是默认选项，通常可以独立回答大多数审查问题——如果截图已经显示了内容，就不要去查看代码来双重确认。只有在您即将声称某些内容缺失时才去查看代码：渲染可能会遗漏实际存在的内容（超出高度限制、在折叠区域、在后续轮播图slide中），因此负面结论值得二次验证。也请注意相反情况——HTML中存在的元素可能对用户仍然不可见。

实现设计

当用户想要将设计实现为代码（而不仅仅是预览）时，始终获取组件HTML代码。不要仅依赖截图。

使用 GET /api/v1/projects/:id/components/:componentId 获取每个界面的代码。componentId 来自聊天运行的 result.operations。

组件代码可能很大。将其保存到文件时，避免通过文本输出写入内容：这会很慢且浪费令牌。相反，使用shell命令获取API响应并直接写入磁盘（例如，将响应体管道传输到文件）。

使用哪个版本

每个组件都带有一个 versions[] 数组和一个 activeVersion: number。默认情况下，使用 versions[i].version === activeVersion 的条目：这是Sleek中当前显示的代码。

如果用户的提示指定了特定版本，则遵循这些版本（参见下面的固定版本）。

固定版本

用户的提示可能包含一个固定块，告诉您实现特定的历史版本而不是当前版本，如下所示：

... at this exact state instead of the project's current version:
- component cmp_abc: version ver_001
- component cmp_def: version ver_002
- theme thm_ghi: version ver_003

当您看到固定块时，请实现那些确切的版本而不是 activeVersion。未在固定块中命名的组件继续使用它们的活动版本。主题ID仅在固定块中出现；此技能不暴露单独的端点来枚举它们。

获取正确的代码

对于每个固定的组件，在 versions[] 中找到 versions[i].id 与给定版本id（例如 ver_001）匹配的条目，并使用其 code。对于固定的组件，不要回退到 activeVersion。

固定版本的截图

将 componentVersionOverrides 和 themeVersionOverrides 传递给 POST /api/v1/screenshots：

{
  "componentIds": ["cmp_abc"],
  "projectId": "proj_xyz",
  "componentVersionOverrides": { "cmp_abc": "ver_001" },
  "themeVersionOverrides": { "thm_ghi": "ver_003" }
}

键是组件/主题的公开id；值是对应的 versions[i].id。映射中缺失的实体回退到它们的活动版本。只要提示指定了固定版本，就包含覆盖映射。

HTML原型

组件 code 是一个完整的HTML文档。直接将其保存为 .html 文件。无需构建步骤。

原生框架（React Native、SwiftUI等）

同时使用HTML代码和截图：

HTML代码 是实现参考：它包含准确的结构、布局、样式、颜色、间距、内容、图像URL和图标名称。
截图是视觉目标：使用它们来验证您的实现与预期外观匹配。

HTML告诉您如何构建它；截图告诉您 它应该是什么样子。

图标

Sleek使用 Iconify 图标，格式为 prefix:name（例如 solar:heart-bold、material-symbols:search-rounded、lucide:settings）。最常见的集合是 Solar、Hugeicons、Material Symbols 和 MDI。

使用HTML代码中的准确图标。不要替换为不同的图标集。匹配图标

移动应用设计