點解 Codia 會開放 API
Codia 產品會將視覺內容轉成可編輯、結構化資產。API 係畀想將同樣能力放入自己產品、遷移腳本、agent 工作流程、QA 系統或者設計自動化 pipeline 嘅團隊用。
開發者平台背後嘅核心想法好簡單：視覺輸入應該變成軟體可以推理嘅結構化資料。
圖像用嘅 Visual Struct
Visual Struct 圖像 endpoint 會將 UI 截圖或者 mockup 轉成階層式 JSON tree。
POST https://api.codia.ai/v1/open/image_to_design回應會包含 header、button、card、table、chart、icon、text、panel 等有型別元素。節點包含邊界框、版面配置、信心度 metadata 同子元素。
文件講解咗三種輸出格式：
json：畀自訂下游 pipeline 用svg：畀唔綁定設計工具嘅向量重繪用figma：透過 plugin 或 import flow 插入 Figma 檔案
當截圖、UI mockup 或視覺參考要變成機器可讀資料時，就用呢個 API。
PDF to Visual Struct
PDF 有對應 endpoint：
POST https://api.codia.ai/v1/open/pdf_to_design呢個 endpoint 會將 PDF 頁面轉成 Codia 嘅 Visual Element Schema：包含邊界框、版面配置、樣式規格同子元素嘅有型別階層結構。佢同圖片 Visual Struct 共用同一套 schema 形狀，所以下游系統可以用同一種處理模型支援圖片同 PDF。
文件列出嘅常見用途包括 Figma importer、程式碼生成器、視覺 QA pipeline 同渲染工作流程。
上傳與任務工作流程
對於需要私有檔案處理或者長時間工作的 workflow，現有 Open API 內容講解咗 upload + task 模式：
- 將 private file 上傳到
/v1/open/uploads - 取得 opaque 嘅
upload_id - 透過
/v1/open/tasks建立 task - 接收 webhook events 或 poll task 狀態
- task 完成後下載生成結果
NotebookLM-style PDF to editable PPTX 文章就係用呢個模式做 server-side PDF-to-PowerPoint 自動化。關鍵實作規則係 Codia API key 要放喺 server，唔好放喺 browser。
開發者可以用嚟做乜
當團隊需要將結構化視覺理解接入另一個系統時，呢個 API 好有用：
- 競品 UI 歸檔同分析
- design system audit
- 自動化視覺 QA 同 regression check
- Screenshot to Figma import flow
- PDF-to-schema 擷取
- 程式碼生成前處理
- 需要機器可讀 UI 結構嘅 agent 工作流程
- 大型設計檔案庫嘅批次遷移工具
輸出唔只係有標籤嘅截圖，而係一棵可以被過濾、轉換、渲染、匯入，或者交畀另一個模型嘅 tree。
整合邊界
公開文件講得好清楚幾個實際邊界：
- API 呼叫需要 Bearer token 認證
- 某啲上傳會先檢查 credits，之後先讀檔
- 輸出品質取決於來源清晰度同版面複雜度
- 好長嘅截圖如果喺區塊邊界切分，會更穩定
- 下游使用前應過濾低信心節點
- 企業部署可以檢視保留、正式使用、更高 rate limits 同 private deployment 需求
呢啲邊界本身都係開發者體驗嘅一部分。可靠嘅 API 應該將自己嘅取捨講清楚。
從邊度開始
截圖同 mockup 先由 Visual Struct 開始。PDF 就用 PDF to Visual Struct。endpoint schema 同 request/response 欄位請睇 API Reference。