PDF to Visual Struct

概覽

PDF to Visual Struct 把一頁 PDF 轉換為 Codia Visual Element Schema：一棵強型別的階層 JSON 元素樹，帶有邊界框、佈局設定與樣式規格。該 Schema 與 Codia Studio 同源，下游消費方（Figma 匯入器、程式碼產生器、視覺 QA 流水線）可以基於同一套穩定資料結構工作。

端點

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

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

請求

請求為 multipart/form-data。

欄位	型別	必填	說明
`pdf_file`	file	是	待轉換的 PDF 檔案。每次請求單檔。
`page_no`	string	是	從 0 開始的頁碼。多頁在用戶端並行迴圈。

範例

bash

curl 'https://api.codia.ai/v1/open/pdf_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --form 'pdf_file=@"xx.pdf"' \
  --form 'page_no="0"'

回應

json

{
  "configuration": {
    "scalingFactor": 1,
    "baseWidth": 1940,
    "measurementUnit": "px"
  },
  "pages": [
    {
      "visualElement": { /* 根元素 */ }
    }
  ],
  "size": {
    "height": 1080,
    "width": 1940
  }
}

頂層欄位

欄位	說明
`configuration.baseWidth`	佈局求解時使用的參考寬度。在不同視埠寬度算繪時按比例縮放邊界框。
`configuration.measurementUnit`	座標單位，通常為 `px`。
`configuration.scalingFactor`	預套用縮放比。通常為 `1`。
`size.width`、`size.height`	基礎座標系下求解的頁面畫布。
`pages[].visualElement`	頁面樹根節點。沿 `childElements` 遞迴。

Visual Element Schema

每個節點結構相同：

json

{
  "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": []
}

欄位參考

欄位	說明
`elementId`	在本次回應內穩定的識別碼；跨頁不保證全域唯一。
`elementType`	強型別元素類別：`Panel`、`Text`、`Image`、`Icon`、`Button`、`Table`、`Chart` 以及 50+ 其他型別。
`boundingBox`	基礎座標下的 `[x, y, width, height]`。
`layoutConfig.positionMode`	`Normal`（流式）或 `Absolute`。
`layoutConfig.flexibleMode`	`Row`、`Column` 或 `Absolute`，對齊 Figma auto-layout。
`styleConfig.widthSpec.sizing`	`FIXED`、`FILL_CONTAINER` 或 `HUG_CONTENT`。
`styleConfig.backgroundSpec`	背景：顏色、漸層或影像。
`processingMeta.detectionScore`	偵測信心度，0.0 – 1.0。下游使用前過濾低信心節點。
`childElements`	子元素陣列，深度走訪得到完整階層。

限制

項目	預設值
單檔大小上限	50 MB
單文件頁數上限	100
每分鐘請求上限	取決於方案，詳見定價。
單頁典型延遲	600 ms – 2 s

支援的輸入

文字型 PDF（設計工具、辦公軟體或程式產生）——保真度最高。
掃描 PDF —— 自動 OCR；低解析度掃描件雜訊較多。
不支援帶密碼保護的 PDF，請先解鎖。

常見模式

多頁轉換

在方案並行上限內，從 0 到總頁數並行迴圈：

const pages = await Promise.all(
  pageNumbers.map((n) => fetch(ENDPOINT, buildRequest(file, n))),
)

過濾低信心節點

function prune(node, minScore = 0.6) {
  node.childElements = (node.childElements || [])
    .filter((c) => c.processingMeta.detectionScore >= minScore)
    .map((c) => prune(c, minScore))
  return node
}

回寫 Figma

由於 layoutConfig 對齊 Figma auto-layout，可直接作為 auto-layout 框架匯入。不想自建匯入器，使用 PDF to Design Figma 外掛。

常見問題

能一次轉換整份文件嗎？

不能——端點按頁工作。在用戶端迴圈並並行。

轉換有多準？

實際識別品質取決於 PDF 來源、文字清晰度和結構複雜度。掃描法律表單與手寫輸入更低，務必查看 processingMeta.detectionScore。

字型會保留嗎？

字型名、字級、字重、顏色都保留在 styleConfig 中。算繪時需要在消費端安裝原字型。

有 SDK 嗎？

不需要——API 是純 HTTP + JSON。官方 SDK 在路線圖上。

能私有化部署嗎？

企業方案支援。請聯繫 [email protected]。

下一步

Visual Struct —— 同 Schema，影像輸入。
Remove BG —— 產生透明背景圖，便於合成算繪輸出。
完整端點參考：/api#convert-pdf-to-design。