使用 Sleek 进行设计

概述

sleek.design 是一款由人工智能驱动的移动应用设计工具。您可以通过 /api/v1/* 上的 REST API 与其交互，创建项目，用通俗的语言描述您想要构建的内容，并获得渲染后的屏幕。所有通信均为标准 HTTP 协议，并使用令牌持有者身份验证。

基础 URL: https://sleek.design
认证: 在每个 /api/v1/* 请求中包含 Authorization: Bearer $SLEEK_API_KEY
Content-Type: application/json (请求和响应)
CORS: 已在所有 /api/v1/* 端点启用

先决条件：API 密钥

在 https://sleek.design/dashboard/api-keys 创建 API 密钥。完整的密钥值仅在创建时显示一次 — 将其存储在 SLEEK_API_KEY 环境变量中。

所需套餐: Pro+（API 访问权限受套餐限制）

密钥权限范围

仅使用任务所需的范围创建密钥。

安全与隐私

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

处理高级请求

当用户说出诸如“设计一个健身追踪应用”或“为我构建一个设置屏幕”之类的话时：

1. 创建项目（如果尚不存在）— 向用户询问名称，或从请求中推导出一个名称
2. 发送聊天消息，描述要构建的内容 — 您可以直接使用用户的文字作为 message.text；Sleek 的 AI 会解释自然语言
3. 遵循下面的截图交付规则向用户展示结果

您不需要先将请求分解成多个屏幕。将完整意图作为一条消息发送，让 Sleek 决定要创建哪些屏幕。

截图交付规则

在每次产生 screen_created 或 screen_updated 操作的聊天运行之后，务必截取截图并向用户展示。 切勿在未交付视觉效果的情况下静默完成聊天运行。

当项目首次创建屏幕时（即运行包含 screen_created 操作），交付：

1. 每个新创建屏幕的单张截图（使用单独的 componentIds: [screenId]）
2. 项目中所有屏幕的组合截图（使用 componentIds: [所有屏幕ID]）

当仅更新现有屏幕时，为每个受影响的屏幕交付一张截图。

除非用户明确要求，否则所有截图均使用 background: "transparent"。

快速参考 — 所有端点

所有 ID 均为稳定的字符串标识符。

端点

项目

列出项目

GET /api/v1/projects?limit=50&offset=0
Authorization: Bearer $SLEEK_API_KEY

响应 200:

{
  "data": [
    {
      "id": "proj_abc",
      "name": "我的应用",
      "slug": "my-app",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "..."
    }
  ],
  "pagination": { "total": 12, "limit": 50, "offset": 0 }
}

创建项目

POST /api/v1/projects
Authorization: Bearer $SLEEK_API_KEY
Content-Type: application/json

{ "name": "我的新应用" }

响应 201 — 与单个项目形状相同。

获取/删除项目

GET    /api/v1/projects/:projectId
DELETE /api/v1/projects/:projectId   → 204 无内容

组件

列出组件

GET /api/v1/projects/:projectId/components?limit=50&offset=0
Authorization: Bearer $SLEEK_API_KEY

响应 200:

{
  "data": [
    {
      "id": "cmp_xyz",
      "name": "英雄区域",
      "activeVersion": 3,
      "versions": [{ "id": "ver_001", "version": 1, "createdAt": "..." }],
      "createdAt": "...",
      "updatedAt": "..."
    }
  ],
  "pagination": { "total": 5, "limit": 50, "offset": 0 }
}

聊天 — 发送消息

这是核心操作：在 message.text 中描述您想要的内容，AI 将创建或修改屏幕。

POST /api/v1/projects/:projectId/chat/messages?wait=false
Authorization: Bearer $SLEEK_API_KEY
Content-Type: application/json
idempotency-key: <可选，最大 255 字符>

{
  "message": { "text": "添加一个包含三个档次的定价部分" },
  "imageUrls": ["https://example.com/ref.png"],
  "target": { "screenId": "scr_abc" }
}

响应 — 异步（默认，wait=false）

状态 202 已接受。在运行达到最终状态之前，result 和 error 不存在。

{
  "data": {
    "runId": "run_111",
    "status": "queued",
    "statusUrl": "/api/v1/projects/proj_abc/chat/runs/run_111"
  }
}

响应 — 同步（wait=true）

最多阻塞 300 秒。完成时返回 200，超时则返回 202。

{
  "data": {
    "runId": "run_111",
    "status": "completed",
    "statusUrl": "...",
    "result": {
      "assistantText": "我添加了一个包含...",
      "operations": [
        { "type": "screen_created", "screenId": "scr_xyz", "screenName": "定价" },
        { "type": "screen_updated", "screenId": "scr_abc" },
        { "type": "theme_updated" }
      ]
    }
  }
}

聊天 — 轮询运行状态

在异步发送后使用此端点检查进度。

GET /api/v1/projects/:projectId/chat/runs/:runId
Authorization: Bearer $SLEEK_API_KEY

响应 — 与发送消息的 data 对象形状相同：

{
  "data": {
    "runId": "run_111",
    "status": "queued",
    "statusUrl": "..."
  }
}

成功完成时，result 存在：

{
  "data": {
    "runId": "run_111",
    "status": "completed",
    "statusUrl": "...",
    "result": {
      "assistantText": "...",
      "operations": [...]
    }
  }
}

失败时，error 存在：

{
  "data": {
    "runId": "run_111",
    "status": "failed",
    "statusUrl": "...",
    "error": { "code": "execution_failed", "message": "..." }
  }
}

运行状态生命周期: queued → running → completed | failed

截图

拍摄一个或多个渲染组件的快照。

POST /api/v1/screenshots
Authorization: Bearer $SLEEK_API_KEY
Content-Type: application/json

{
  "componentIds": ["cmp_xyz", "cmp_abc"],
  "projectId": "proj_abc",
  "format": "png",
  "scale": 2,
  "gap": 40,
  "padding": 40,
  "background": "transparent"
}

内边距解析有一个级联顺序：各边 → 轴向 → 统一。例如，{ "padding": 20, "paddingX": 10, "paddingLeft": 5 } 会得到上/下 20px，右 10px，左 5px。

当 showDots 为 true 时，会在背景颜色上绘制点图案。点会自动适应背景：深色背景为亮色点，浅色背景为暗色点。当 background 为 "transparent" 时，此设置无效。

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

响应：原始二进制 image/png 或 image/webp，带有 Content-Disposition: attachment 标头。

错误格式

{ "code": "UNAUTHORIZED", "message": "..." }

聊天运行级别的错误（位于 data.error 内）：

工作流程

工作流 1：创建项目并生成 UI（异步 + 轮询）

1. POST /api/v1/projects                              → 获取 projectId
2. POST /api/v1/projects/:id/chat/messages            → 获取 runId (202)
3. 轮询 GET /api/v1/projects/:id/chat/runs/:runId
   直到状态变为 "completed" 或 "failed"
4. 从 result.operations 收集 screenIds
   （包括 screen_created 和 screen_updated 条目）
5. 分别截取每个受影响的屏幕
6. 如果有任何 screen_created：同时截取项目所有屏幕的组合截图
7. 向用户展示所有截图

轮询建议：从 2 秒间隔开始，10 秒后退避到 5 秒，5 分钟后放弃。

工作流 2：同步模式（简单，阻塞）

最适合短任务或延迟可接受的情况。

1. POST /api/v1/projects/:id/chat/messages?wait=true
   → 最多阻塞 300 秒
   → 完成返回 200，超时返回 202
2. 如果返回 202，回退到使用返回的 runId 进行工作流 1 的轮询
3. 完成后，截取并展示受影响的屏幕（参见截图交付规则）

工作流 3：编辑特定屏幕

1. GET /api/v1/projects/:id/components         → 查找 screenId
2. POST /api/v1/projects/:id/chat/messages
   请求体: { message: { text: "..." }, target: { screenId: "scr_xyz" } }
3. 按上述方式轮询或等待
4. 截取更新后的屏幕并向用户展示

工作流 4：幂等消息（安全重试）

在发送请求时添加 idempotency-key 标头。如果网络中断并且您使用相同的密钥重试，服务器将返回现有的运行，而不是创建重复的。密钥长度不得超过 255 个字符。

POST /api/v1/projects/:id/chat/messages
idempotency-key: my-unique-request-id-abc123

工作流 5：一次一个运行（冲突处理）

每个项目一次只允许一个活动运行。如果您在某个运行正在进行时发送消息，您将收到 409 CONFLICT。等待活动运行完成后再发送下一条消息。

409 响应 → 轮询现有运行 → 完成 → 发送下一条消息

分页

所有列表端点均接受 limit（1–100，默认 50）和 offset（≥0）。响应始终包含 pagination.total，因此您可以遍历所有结果。

GET /api/v1/projects?limit=10&offset=20

常见错误