design-mobile-apps

使用 Sleek 进行设计

概述

sleek.design 提供 /api/v1/* 下的 REST API，可用于创建项目、根据简报设计屏幕，以及获取屏幕的 HTML 和渲染图。

基础 URL：https://sleek.design 身份验证：Authorization: Bearer $SLEEK_API_KEY，公开的设备启动和轮询端点除外 Content-Type：JSON 请求正文请发送 application/json。 CORS：所有 /api/v1/* 端点均已启用 响应封装：先检查 HTTP 状态码。成功的 JSON 响应会将负载封装在 data 中；列表还会包含同级的 pagination。错误响应在顶层包含 code、status 和 message，并可选包含 data.url。成功的截图和分享卡片会返回图像字节；204 没有响应正文。 ID：不透明的 11 字符令牌，例如 V1StGXR8Z5j，没有类型前缀。仅凭 ID 无法判断它指代项目、屏幕、组件、版本还是主题，因此请根据它所在的响应字段分别记录。 解析响应：将响应正文写入文件（curl -o run.json），然后解析该文件。通过 echo 管道传递 JSON 会导致内容损坏：zsh 会将字符串值中转义的 \n 展开为实际换行符，从而使正文成为无效 JSON。 API 文档：OpenAPI 规范位于 https://sleek.design/api/v1/spec.json；可浏览的文档位于 https://sleek.design/api/v1/docs。如需了解此处未涵盖的契约细节，请获取规范。

---

设计或实现

一次运行可以兼顾这两个方向——“帮我设计一个健身应用并用 Expo 构建”就是先进行设计，再进行实现。应根据眼前的产物决定何时查阅各文档，而不是只在阅读请求时查阅一次：

设计——你即将向 Sleek 发送聊天消息。请先阅读 designing.md；该文档介绍了创建 → 聊天 → 截图的循环、如何编写风格方向，以及何时应改为从参考内容开始。

**实现。**在根据 Sleek 设计编写代码之前，请阅读 implementing.md，了解版本选择、原生转换、可用功能和验收检查。

用户截图和评审截图

截图有两种取景方式，下面的每个文件都会明确指定其中一种：

• 用户截图是默认渲染图：视口高度，呈手机形状。这是展示给用户的截图。
• 评审截图会添加 fullHeight: true，每个请求对应一个组件。这是用于对照评估你自己工作成果的截图。

---

前提条件：API Key

如果未设置 SLEEK_API_KEY，请使用设备授权流程，这样用户就不必接触原始密钥：

1. 使用请求体 {"source": "your-tool-slug"} 向 https://sleek.design/api/v1/device/start 发送 POST 请求（无需身份验证）。响应中包含 verificationUrl、供用户核对的 userCode、机密的 deviceCode，以及以秒为单位的轮询 interval。
2. 向用户展示 verificationUrl 和 userCode，并告知他们在批准前确认验证码是否匹配。
3. 每隔 interval 秒，使用 {"deviceCode": "..."} 向 https://sleek.design/api/v1/device/poll 发送 POST 请求。遇到 pending 时继续等待。遇到 approved 时，在首次读取时将 data.key 私下保存为 SLEEK_API_KEY：密钥只会交付一次。遇到 expired 或 404 NOT_FOUND 时，重新开始授权流程。有关响应约定，请参阅 设备：轮询。

备用方案：引导用户访问 **https://sleek.design/agents/setup**，该页面会在一个地方处理登录、升级套餐和创建密钥，并请用户将密钥粘贴给你。也可以在 https://sleek.design/dashboard/api-keys 管理密钥。完整密钥值只会在创建时显示一次，免费账户一次只能持有一个有效密钥。

套餐：免费账户可使用一次性试用额度体验 API（约可运行一次设计任务），让新用户在决定是否付费前看到自己的第一个设计。持续使用需要 Pro 套餐或更高级别。本文件有意不列出具体数值——请从 https://sleek.design/agents.md 获取当前价格、计费周期和额度；该文件由 Sleek 的实时定价信息生成。当费用成为相关事项时（用户询问、需要升级才能继续，或你即将引导用户前往付款页面），请清楚说明定价，包括按年付费选项，让用户在到达付款步骤前就知道即将付费。

---

快速参考：所有端点

API 提供的所有端点：

方法	路径	权限范围
GET	/api/v1/projects	projects:read
POST	/api/v1/projects	projects:write
GET	/api/v1/projects/:id	projects:read
DELETE	/api/v1/projects/:id	projects:write
GET	/api/v1/projects/:id/components	components:read
GET	/api/v1/projects/:id/components/:componentId	components:read
GET	/api/v1/references	任意有效密钥
POST	/api/v1/projects/:id/chat/messages	chats:write
GET	/api/v1/projects/:id/chat/runs/:runId	chats:read
POST	/api/v1/projects/:id/chat/runs/:runId/cancel	chats:write
POST	/api/v1/screenshots	screenshots
POST	/api/v1/share-cards	screenshots
POST	/api/v1/device/start	公开，无需身份验证
POST	/api/v1/device/poll	公开，无需身份验证

创建密钥时，只授予任务所需的权限范围。

上表中的每一行都在 endpoints.md 中作了完整说明，包括请求体、响应结构、字段默认值和状态码。此表足以用于选择端点；需要了解表中未涵盖的约定细节时，请查阅参考文档。

---

错误类型

{
  "defined": true,
  "code": "FORBIDDEN",
  "status": 403,
  "message": "...",
  "data": { "url": "https://sleek.design/..." }
}

HTTP	Code	When
401	UNAUTHORIZED	API 密钥缺失、无效或已过期
403	FORBIDDEN	密钥有效，但权限范围或套餐不匹配
404	NOT_FOUND	资源不存在
400	BAD_REQUEST	验证失败
409	CONFLICT	此项目已有另一个运行正在进行
429	TOO_MANY_REQUESTS	渲染上限：每个组织每小时 1000 张截图和分享卡片，仅统计 API 密钥请求
500	INTERNAL_SERVER_ERROR	服务端错误

401、403 和 429 响应正文可能包含 data.url：用户可在该页面修复问题（创建密钥、升级套餐）。请原样分享该链接。

聊天运行级错误（位于 data.error 中）：

Code	Meaning
out_of_credits	组织的额度已用尽
execution_failed	AI 执行错误
cancelled	通过取消端点取消运行
request_message_persist_failed	运行在到达 AI 前失败；消息从未被存储

对于 out_of_credits，转发 error.url 并等待用户解决问题。发生任一可恢复故障后，重放还是重新尝试，请遵循安全重试中的说明。