使用 Sleek 設計

概述

sleek.design 是一個由 AI 驅動的行動應用程式設計工具。您可以透過 /api/v1/* 的 REST API 與之互動，以建立專案、用白話描述您想要建置的內容，並取得渲染後的畫面。所有通訊皆為標準 HTTP，並使用承載者令牌認證。

基礎 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 文件：OpenAPI 規格在 https://sleek.design/api/v1/spec.json；可瀏覽的文件在 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 分鐘後過期；如果收到 expired，則重新開始。

備用方案：將使用者引導至 **https://sleek.design/agents/setup**，該頁面會在同一處處理登入、方案升級和金鑰建立，並請他們將金鑰貼回給您。金鑰也可以在 https://sleek.design/dashboard/api-keys 管理。完整的金鑰值僅在建立時顯示一次。

方案：免費帳戶可以使用一次性的試用點數（大約可以執行一次設計）來嘗試 API，因此新使用者在做出任何付款決定之前，可以先看到他們的第一個設計。持續使用需要 Professional 方案或更高級別（每月 $49.99 美元，或每年 $360 美元，相當於每月 $30 美元；包含每月 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 個形容詞）、色彩策略（邏輯，而非十六進位色碼）、字體感覺、佈局理念、元件樣式（圓角、邊框 vs 陰影、導航處理方式）、圖像和插圖風格，以及一兩個獨特的細節。要對色板、字體方向和整體感覺做出承諾——任何只設定氛圍的內容都只是一個提示，而非方向。要有主見，不要含糊其辭。將個性體現在顏色、字體和圖像中，而不是不尋常的佈局或導航。

擴展使用者給您的內容，永遠不要與之矛盾。當他們指向參考圖片或他們喜歡的應用程式時，研究每一個，並將您學到的東西帶入方向中——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"。

將螢幕截圖保存在專案目錄（而不是暫存資料夾）中，以便使用者輕鬆檢視。

顯示 vs 審查：預設值僅捕獲視口，這對於使用者來說是正確的取景——畫面看起來像手機畫面。但這對於判斷您自己的工作來說是錯誤的取景，因為摺頁以下的所有內容都會被裁剪掉。當您要審查執行的結果時，請使用 fullHeight: true（每個請求一個畫面）重新拍攝畫面，以查看整個可滾動頁面。

螢幕截圖請求是獨立的，因此請平行發出——用戶面向的截圖和您的 fullHeight 審查截圖一起發出，不同畫面的截圖也是如此。「每個請求一個畫面」管理的是每個圖像中包含的內容，而不是您發送它們的速度；這不是等待一個回應後再開始下一個的理由。只有在您實際收到 429 時才進行回退。

切勿僅從視口螢幕截圖就斷定畫面不完整。 看起來缺少的內容幾乎總是在摺頁下方。在告知使用者某物缺失之前，或發送後續訊息要求 Sleek 添加它之前，請通過整個畫面進行確認：使用 fullHeight: true 的螢幕截圖，或來自 GET /api/v1/projects/:id/components/:componentId 的元件 HTML，後者是畫面上的實際內容。螢幕截圖是預設選項，並且可以自行回答大多數審查問題——不要為了雙重檢查它已經顯示的內容而去查看程式碼。只有在您即將聲稱某物缺失時，才去查看程式碼：渲染可能會遺漏實際存在的內容（超出高度限制、在折疊的部分、在後面的輪播滑動中），因此負面結論才值得第二個來源驗證。也要注意相反的情況——HTML 中存在的元素可能對用戶來說仍然不可見。

實作設計

當使用者想要在程式碼中實作設計（而不僅僅是預覽）時，始終擷取元件 HTML 程式碼。不要僅依賴螢幕截圖。

使用 GET /api/v1/projects/:id/components/:componentId 來擷取每個畫面的程式碼。componentId 來自聊天執行的 result.operations。

元件程式碼可能很大。在將其儲存到檔案時，避免透過文字輸出寫入內容：這很慢且浪費令牌。相反，請使用 shell 命令來擷取 API 回應並將其直接寫入磁碟（例如，將回應主體導向到檔案中）。

要使用的版本

每個元件都有一個 versions[] 陣列和一個 activeVersion: number。預設情況下，使用 versions[i].version === activeVersion 的條目：這是在 Sleek 中目前顯示的程式碼。

如果使用者的提示指定了特定版本，則改為遵循這些版本（請參閱下方的固定版本）。

固定版本

使用者的提示可能包含一個固定區塊，告訴您要實作特定的歷史版本，而不是當前的版本，如下所示：

... 以這個確切的狀態，而不是專案的當前版本：
- 元件 cmp_abc：版本 ver_001
- 元件 cmp_def：版本 ver_002
- 主題 thm_ghi：版本 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 的圖示，格式為 前綴:名稱（例如，solar:heart-bold、material-symbols:search-rounded、lucide:settings）。最常見的集合是 Solar、Hugeicons、Material Symbols 和 MDI。

使用 HTML 程式碼中確切的圖示。不要用不同的圖示集來替代。匹配圖示名稱時...

設計行動應用程式