為什麼 Codia 會提供 API
Codia 產品會把視覺內容轉成可編輯、結構化的資產。API 是給那些想把同樣能力放進自家產品、遷移腳本、agent 工作流程、QA 系統或設計自動化管線的團隊使用。
開發者平台的核心想法很簡單：視覺輸入應該變成軟體可以推理的結構化資料。
圖片用的 Visual Struct
Visual Struct 圖片端點會把 UI 截圖或 mockup 轉成階層式 JSON 樹。
POST https://api.codia.ai/v1/open/image_to_design回應會包含 header、button、card、table、chart、icon、text、panel 等有型別元素。節點包含邊界框、版面配置、信心度中繼資料與子元素。
文件說明了三種輸出格式：
json：給自訂下游管線用svg：給不綁定設計工具的向量重繪用figma：透過外掛或匯入流程插入 Figma 檔案
當截圖、UI mockup 或視覺參考需要變成機器可讀資料時，就用這個 API。
PDF to Visual Struct
PDF 有相對應的端點：
POST https://api.codia.ai/v1/open/pdf_to_design這個端點會把 PDF 頁面轉成 Codia 的 Visual Element Schema：包含邊界框、版面配置、樣式規格與子元素的有型別階層結構。它與圖片 Visual Struct 共用同一套 schema 形狀，因此下游系統可以用同一種處理模型支援圖片與 PDF。
文件列出的常見用途包括 Figma importer、程式碼生成器、視覺 QA 管線與渲染工作流程。
上傳與任務工作流程
對於需要私有檔案處理或長時間作業的工作流程，現有 Open API 內容描述了上傳加任務的模式：
- 將 private file 上傳到
/v1/open/uploads - 取得 opaque 的
upload_id - 透過
/v1/open/tasks建立 task - 接收 webhook 事件或輪詢 task 狀態
- task 完成後下載生成結果
NotebookLM-style PDF to editable PPTX 文章就是用這個模式做 server-side PDF-to-PowerPoint 自動化。關鍵實作原則是，Codia API key 要放在 server 端，而不是瀏覽器裡。
開發者會用它做什麼
當團隊需要把結構化視覺理解接進另一個系統時，這個 API 很有用：
- 競品 UI 歸檔與分析
- 設計系統稽核
- 自動化視覺 QA 與回歸檢查
- Screenshot to Figma 匯入流程
- PDF-to-schema 擷取
- 程式碼生成前處理
- 需要機器可讀 UI 結構的 agent 工作流程
- 大型設計檔案庫的批次遷移工具
輸出不只是貼了標籤的截圖，而是一棵可以被過濾、轉換、渲染、匯入，或交給另一個模型的樹。
整合邊界
公開文件把幾個實際邊界說得很清楚：
- API 呼叫需要 Bearer token 驗證
- 某些上傳會先檢查 credits，再讀取檔案
- 輸出品質取決於來源清晰度與版面複雜度
- 很長的截圖在區塊邊界切分後會更穩定
- 下游使用前應過濾低信心節點
- 企業部署可檢視保留、正式使用、更高 rate limits 與 private deployment 需求
這些邊界本身也是開發者體驗的一部分。可靠的 API 應該把自己的取捨說清楚。
從哪裡開始
截圖與 mockup 先從 Visual Struct 開始。PDF 則使用 PDF to Visual Struct。端點 schema 與 request/response 欄位請見 API Reference。