Visual Struct

概覽

Visual Struct 接收一張 UI 截圖或 mockup，回傳其中每個元素的階層 JSON 描述。每個元素都有型別（header、button、card、table 等）、定位（像素精度的邊界框），並與父節點建立階層，把整張影像表示為一棵樹。

該 Schema 與 PDF to Visual Struct 共享，下游可用同一程式碼路徑消費兩種輸入。

端點

POSThttps://api.codia.ai/v1/open/image_to_design

透過 Bearer Token 驗證。在 codia.ai/dashboard/developer 取得 Key。

請求

欄位	型別	必填	說明
`image_url`	string	是（或 `image_base64`）	可公開存取的來源影像 URL。
`image_base64`	string	是（或 `image_url`）	Base64 編碼的影像資料。
`output_format`	string	否	`json`（預設）、`svg` 或 `figma`。

範例

bash

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" }'

回應

json

{
  "elementId": "header_section_001",
  "elementName": "HeaderSection",
  "elementType": "header",
  "displayName": "Header Section",
  "layoutConfig": {
    "positionMode": "flex",
    "flexibleMode": "row",
    "flexAttributes": {
      "justifyContent": "space-between",
      "alignItems": "center"
    }
  },
  "childElements": [ /* 巢狀元素 */ ]
}

欄位參考

欄位	說明
`elementType`	元素類別：`header`、`button`、`card`、`badge`、`icon`、`tab`、`table`、`chart` 等。
`layoutConfig.positionMode`	`flex` 或 `absolute`。Flex 容器暴露 `flexibleMode`（`row`/`column`）和 `flexAttributes`。
`boundingBox`	來源影像像素座標下的 `[x, y, width, height]`。
`processingMeta.detectionScore`	0–1 信心度。
`childElements`	遞迴的子元素陣列。

輸出格式

格式	用途
`json`	預設，最適合自訂下游流水線。
`svg`	無損向量重繪，與設計工具無關。
`figma`	可透過 REST / 外掛 API 直接插入 Figma 的節點結構。

三種格式都由同一底層 Schema 後處理而來。

能力

能力	數值
元素比對品質	取決於來源檔案清晰度與結構複雜度
典型延遲	2–5 秒 / 圖
OCR 語言	50+
單圖大小上限	25 MB
建議解析度	長邊 600–4000 px
可用性	以当前服务状态和适用协议为准

常見模式

按信心度過濾

function visibleElements(tree, threshold = 0.6) {
  const out = []
  const walk = (n) => {
    if ((n.processingMeta?.detectionScore ?? 1) >= threshold) {
      out.push(n)
      ;(n.childElements ?? []).forEach(walk)
    }
  }
  walk(tree)
  return out
}

超長截圖

整頁行銷站截圖（10k+ 像素高）可運作，但在呼叫前按自然分段切分能得到更穩定的頂層分組。

暗色 UI

偵測器不依賴背景假設。擷取到的顏色反映螢幕像素——若你需要語意 token（設計時的品牌色而非顯示色），請在消費端對映回你的 token 系統。

常見問題

混合語言 UI 如何處理？

OCR 按文字區塊偵測語言，因此英文控制項配日文正文能在一次請求內被正確處理。

API 會儲存上傳的圖片嗎？

僅在完成請求、產生回應 URL 所需的時間內保留。企業部署可自訂保留期。

能私有化部署嗎？

可以。同一模型以隔離容器交付企業。請聯繫 [email protected]。

如何處理可捲動區域？

API 回傳扁平的樹，無捲動溢位概念。請基於已知 UI 模式或元素溢位在你這端標註。

下一步

PDF to Visual Struct —— 同 Schema，PDF 輸入。
Design to Code —— 將 Schema 接入程式碼產生。
完整端點參考：/api。