為什麼「結構」才是關鍵單位
對電腦來說，UI 截圖只是一格格像素；對設計師或開發者來說，它是一張卡片、一個標題、一個價格、一個評分、一個按鈕。把這兩種視角打通——把像素變成一棵帶命名、強型別的元素樹——正是 Visual Struct API 的工作。
送一張圖，拿回這張圖中每個 UI 元素的階層 JSON 描述：帶型別、邊界框、文字內容和與父節點的佈局關係。就這樣。不用寫提示詞，不用人工標註，不用在你這邊寫 CV 樣板程式碼。
我們看到團隊用它把競品截圖自動匯入 Figma、驅動行動端視覺回歸、把截圖索引進 AI 搜尋，以及直接基於 Dribbble 作品產生程式碼。本文說明 API 到底回傳什麼，以及如何在其之上建構。
回應的結構
每個元素核心欄位一致。下面是從到達頁截圖裁出的 header：
{
"elementId": "header_section_001",
"elementName": "HeaderSection",
"elementType": "header",
"displayName": "Header Section",
"layoutConfig": {
"positionMode": "flex",
"flexibleMode": "row",
"flexAttributes": {
"justifyContent": "space-between",
"alignItems": "center"
}
},
"boundingBox": [0, 0, 1440, 88],
"childElements": [
{ "elementType": "logo", /* ... */ },
{ "elementType": "nav", /* ... */ },
{ "elementType": "button", "displayName": "Sign Up", /* ... */ }
]
}幾個要點：
elementType是程式化處理的主鍵。API 辨識數十種型別——header、button、input、card、badge、icon、tab、table、chart等——在數百萬真實 UI 上訓練而成。layoutConfig捕捉子元素在父層級內的排列方式。當偵測器看到一排垂直置中、間距相近的元素，它會輸出一個帶justifyContent的flex列。自由定位元素得到absolute。你拿到的是佈局圖，不是一堆框。childElements是遞迴的。整張圖是以頁面容器為根的一棵樹，你可以深度走訪、算繪、比對或索引。- 文字 由多語言 OCR（50+ 種語言）處理，辨識結果會落到正確容器裡，而不是以懸空文字區塊出現。
如何衡量準確率與速度
實際元素比對品質取決於介面類型、截圖清晰度和結構複雜度。端到端延遲通常受解析度、文字密度和佇列狀態影響；可用性以目前服務狀態和適用協議為準。
邊界框的「像素級」含義是：對比人工標註，視覺上清晰的元素 IoU 平均高於 0.9。緊湊佈局中巢狀文字——六欄資料表——偏差最大，這時每個元素上的 detectionScore 派上用場：在下游使用前過濾長尾低信心節點。
輸出格式
預設回應是 JSON。同一端點族提供兩種替代：
- SVG —— 偵測場景的向量重繪。適合需要無損可編輯、且不綁定特定設計工具的場合。
- Figma 相容節點 —— 結構與 Figma 檔案節點一致，可經 REST / 外掛 API 直接匯入。Codia 的 Figma 外掛消費的正是這種格式。
JSON 最彈性；SVG 和 Figma 格式都是圍繞同一底層 Schema 的便利封裝。
五件可做的事
1. 截圖 → Figma 流水線。 你應該見過這類示範：拖一張圖進外掛，拿到完全可編輯的 Figma 檔案。外掛只是 API 的薄客戶端。如果你在自家工具裡做設計匯入，可以跳過外掛直接呼叫 API。
2. 規模化視覺 QA。 與其在 CI 之間做像素級截圖比對，不如比對它們的元素樹。元素級 diff 忽略子像素算繪差異、字型回退和反鋸齒雜訊，並給出人能讀懂的 diff：「按鈕 'Continue' 向右移動 12px，圓角新增 4px。」
3. AI 搜尋的語意索引。 如果你在做「UI 版 Pinterest」——或者只是想讓設計團隊能搜「帶 sparkline 的暗色儀表板」——Schema 提供了可查詢結構。索引元素型別、顏色和文字內容，而不是原始影像。
4. 影像的無障礙 Lint。 截圖本身不可存取；一棵帶型別的元素樹可以。把 JSON 丟進無障礙檢查器，在以 PNG 形式落在工單裡的設計上，就能發現缺失的 alt 文字、低對比度組合或未標註的按鈕。
5. 基於截圖的程式碼產生。 由於本 Schema 與我們的 PDF 與設計流水線共享語意，你可以直接把它導入 Codia 的程式碼產生器，產出 React、Vue、Flutter 或 HTML/Tailwind。描述影像的同一棵樹，也產生了 UI。
邊界情況處理
來自整合實戰的幾點建議：
- 超長截圖（比如整頁行銷站截圖）最好在自然分段處切分。模型也處理 10k 像素高的影像，但分塊能拿到更穩定的頂層分組。
- 暗色模式 UI 受良好支援——偵測器不依賴背景假設——但如果某張截圖是亮色設計的暗色算繪結果，擷取到的顏色會反映螢幕像素，而非底層 token。
- 手繪或草圖級原型 可用，但
elementType分佈會偏向通用的container和text，直到草圖進一步收斂。 - 多個巢狀可捲動區域（一個頁面裡含一個可捲動側欄）會被扁平化為一棵樹。模型不理解捲動，這層得由你自己建模。
快速上手
curl 'https://api.codia.ai/v1/open/image_to_design' \
-H 'Authorization: Bearer {codia_api_key}' \
-H 'Content-Type: application/json' \
--data '{ "image_url": "https://example.com/ui.png" }'- 在 codia.ai/dashboard/developer 取得 Key。
- 送出圖片（URL 或 base64）。1440×900 的桌面截圖是最佳尺寸。
- 走訪樹。如果只關心高信心元素，先按
processingMeta.detectionScore > 0.6過濾再用。 - 完整參考（Schema 定義、速率限制、錯誤碼）在 /api。
如果你在考慮企業工作負載——本地、獨立區域，或特定產品的自訂元素型別——請寄信到 [email protected]。模型相同，交付方式不同。
UI 會繼續以影像形式出現——在 bug 報告、Slack 聊天、Dribbble 作品、競品研究裡。把這些影像當作可查詢結構，就能把原本只能人工完成的大量工作解鎖出來。