PDF 的本質問題
PDF 無所不在——產品規格書、財報、法遵表單、遺留設計交付物——但它們幾乎對自動化毫不友善。一份 PDF 本質上是一串扁平的繪製指令：「移動到 (120, 440)，用 Helvetica 12 渲染字形 'H'，向右移動，渲染 'e'……」。裡面沒有按鈕、卡片或標題的概念，沒有階層結構，甚至連「詞」這種概念都不穩定。
PDF to Visual Struct 就是為彌合這道鴻溝而生。把 PDF 傳送到 POST /v1/open/pdf_to_design，你會得到與 Codia Studio 同源的 Visual Element Schema：一棵階層分明的 JSON 元素樹，每個節點都帶有型別、邊界框、版面設定與樣式規格。這棵樹對機器可讀、對設計師可讀，只差一次轉換就能跑通程式碼。
本文詳細說明 API 的工作方式、回傳的 Schema，以及你能在其之上建構什麼。
呼叫 API
請求是一次 multipart/form-data POST，無需 SDK。
curl 'https://api.codia.ai/v1/open/pdf_to_design' \
-H 'Authorization: Bearer {codia_api_key}' \
-H 'Content-Type: application/json' \
--form 'pdf_file=@"invoice.pdf"' \
--form 'page_no="0"'兩個輸入：PDF 檔案，以及從 0 開始的頁碼。若你有 40 頁文件、要全部轉換，就以迴圈並行呼叫——API 以單頁為無狀態單位，並行壓力下表現良好。官方指標為單文件 100+ 頁、50+ 種元素型別、單頁回應低於 2 秒。實際上多數單頁 PDF 在檔案進入入口後 600–1200 ms 即可回傳。
回應結構
頂層是這樣的：
{
"configuration": {
"scalingFactor": 1,
"baseWidth": 1940,
"measurementUnit": "px"
},
"pages": [
{
"visualElement": { /* 根元素 */ }
}
],
"size": {
"height": 1080,
"width": 1940
}
}configuration 說明座標如何解釋。baseWidth 與 measurementUnit 是參考系——若你要改變視窗尺寸，按比例縮放每個邊界框即可。size 是版面求解後正規化的畫布。
每一頁都有一個 visualElement 根節點。沿 childElements 遞迴深度走訪即可得到整份文件。每個節點都有同樣的核心欄位：
{
"elementId": "pdf_page_1",
"elementName": "PDF Document Page",
"elementType": "Panel",
"displayName": "First Page",
"displayOrder": 0,
"boundingBox": [0, 0, 595, 842],
"layoutConfig": {
"positionMode": "Normal",
"flexibleMode": "Absolute"
},
"styleConfig": {
"widthSpec": { "sizing": "FIXED", "value": 595 },
"heightSpec": { "sizing": "FIXED", "value": 842 },
"backgroundSpec": {
"type": "COLOR",
"backgroundColor": { "rgbValues": [255, 255, 255] }
}
},
"processingMeta": {
"surfaceArea": 501490,
"detectionScore": 0.92,
"textContainerized": false
},
"childElements": []
}重點欄位：
elementType—— 強型別標籤。Panel、Text、Image、Icon、Button、Table、Chart以及數十種其他型別。這是讓輸出可操作的關鍵：你可基於此直接產生 HTML、Flutter 元件或 React 元件，而不再依賴啟發式規則。boundingBox—— 基礎座標系下的[x, y, width, height]。用於在絕對版面中定位子元素，或在後處理時偵測重疊與分組。layoutConfig—— 描述父容器如何擺放子元素（流式、flex 列/欄，或自由定位）。語意與 Figma auto-layout 對齊，回寫 Figma 非常輕鬆。styleConfig—— 寬高策略（FIXED、FILL_CONTAINER、HUG_CONTENT）、背景、邊框、圓角、排版。概念與 CSS 足夠接近，程式碼產生器可直接輸出乾淨的樣式表。processingMeta.detectionScore—— 偵測信心度 0–1。產生下游產物前篩掉低信心節點非常有用。
流水線在做什麼
把 PDF 轉成這份 Schema 並不是一次模型呼叫，而是一條短流水線：
- 光柵化 + 擷取。 解析 PDF 串流，取出文字段、向量路徑與嵌入點陣圖。掃描頁則並行進入 OCR。
- 版面分析。 視覺模型把頁面切分為區塊——頁首、內文、側欄、插圖、表格、圖說——為每塊賦予粗型別。
Panel的邊界來自這裡。 - 元素偵測。 區塊內更密集的模型辨識單獨 UI 元素——按鈕、圖示、表單控制項、圖表系列。
elementType來自這一步。 - 文字聚合。 把字形位置聚合成詞、行、段，掛到最近的容器元素上。
- Schema 組裝。 建構階層、解析父子連結、計算每個元素的樣式、把座標正規化到
baseWidth。
第 2、3 步佔延遲預算的大頭，前後都很輕量。
能在其上建構什麼
Schema 刻意保持通用。實際案例：
設計匯入。 一鍵把遺留 PDF 規格書轉成可編輯的 Figma 頁面。因為版面設定對齊了 Figma auto-layout 語意，自動版面會正確重建。
遺留現代化。 拿一份 500 頁的 PDF 手冊，產生響應式網頁版。每一頁變成一條路由；元素型別驅動元件選擇。
視覺回歸測試。 在兩個建置中渲染同一頁基線，分別通過 API，比較元素樹。元素級差異對字體替換與子像素抗鋸齒遠比像素差異穩定。
帶版面感知的 RAG。 給 PDF 做檢索索引時，丟掉原始文字拉平結果。按元素分塊、保留父子關係，就能回答「第 4 頁的 CTA 是什麼」或「第 11 頁第二張表的第三欄是什麼」，無需模糊啟發式。
圖表擷取。 圖表節點攜帶足夠的中繼資料（軸標、系列色、分組文字），可直接升級為即時圖表元件，而不是轉成截圖。
關於準確率
實際偵測品質取決於 PDF 來源、文字清晰度和版面複雜度。產品設計類 PDF 通常更容易解析；掃描法律文件和手寫表單更難，OCR 雜訊更多、detectionScore 更低，需要篩除。
快速上手
- 在 codia.ai/dashboard/developer 取得 API Key。
- 對手邊任意 PDF 跑上面那條
curl。 - 用你喜歡的語言走訪回應樹——Schema 是純 JSON，不需要 SDK。
- 若想跳過解析、直接拿到 Figma 檔，可使用基於同一條流水線建構的 PDF to Design Figma 外掛。
完整參考、請求/回應格式與錯誤碼在開發者文件。如需更高速率或私有部署，請聯絡 [email protected]——流水線以隔離容器交付，滿足企業資料居留需求。
PDF 不會消失。過去十年，它一直是設計自動化最頑固的最後一哩。給它一份乾淨、強型別的結構，是把它重新變成一等公民的第一步。