为什么 Codia 提供 API
Codia 产品把视觉内容转换为可编辑、结构化的资产。API 面向的是想把同样能力接入自己产品、迁移脚本、智能体工作流、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 导入器、代码生成器、视觉 QA 管线和渲染工作流。
上传与任务工作流
对于需要私有文件处理或长任务的场景，已有 Open API 内容描述了上传 + 任务的模式：
- 上传私有文件到
/v1/open/uploads - 获取不透明的
upload_id - 通过
/v1/open/tasks创建任务 - 接收 webhook 事件或轮询任务状态
- 任务完成后下载生成结果
NotebookLM-style PDF 转可编辑 PPTX 的文章就用这个模式实现服务端 PDF-to-PowerPoint 自动化。关键实现规则是：Codia API key 只放在服务端，不发送到浏览器。
开发者可以构建什么
当团队需要把结构化视觉理解嵌入另一个系统时，API 很有用：
- 竞品 UI 归档与分析
- 设计系统审计
- 自动化视觉 QA 与回归检查
- 截图转 Figma 导入流程
- PDF-to-schema 提取
- 代码生成前处理
- 需要机器可读 UI 结构的智能体工作流
- 大型设计归档的批量迁移工具
输出不只是带标签的截图，而是一棵可以过滤、转换、渲染、导入或继续交给另一个模型处理的树。
集成边界
公开文档对几个实际边界说得很清楚：
- API 调用需要 Bearer token 认证。
- 某些上传会先检查 credits，再读取文件。
- 输出质量取决于源文件清晰度和布局复杂度。
- 超长截图按区块切分后调用，顶层分组会更稳定。
- 下游使用前应过滤低置信度节点。
- 企业部署可以讨论保留期限、生产用量、更高限额和私有部署需求。
这些边界本身也是开发者体验的一部分。可靠的 API 应该把取舍说清楚。
从哪里开始
截图和 mockup 从 Visual Struct 开始。PDF 从 PDF to Visual Struct 开始。完整 endpoint schema 和请求/响应字段见 API Reference。