Codia
← 返回文章列表

Visual Struct API：把 UI 截图转换成结构化 JSON

Engineering2026-04-23

Visual Struct API 是什么

Visual Struct API 会把 UI 截图转换成结构化数据。发送一张图片，返回一棵带元素类型、边界框、文本内容、布局关系和置信度的层级 JSON 树。

对计算机来说，UI 截图只是一格格像素；对设计师或开发者来说，它是一张卡片、一个标题、一个价格、一个评分、一个按钮。API 的作用就是把像素变成软件可以查询和处理的命名元素。

当你需要截图转 JSON、截图转 Figma、视觉 QA、UI 搜索、数据集标注或设计转代码自动化时，就适合使用 Visual Struct。

响应的形状

每个元素核心字段一致。下面是从落地页截图裁出的 header:

json
{ "elementId": "header_section_001", "elementName": "HeaderSection", "elementType": "header", "displayName": "Header Section", "layoutConfig": { "positionMode": "flex", "flexibleMode": "row", "flexAttributes": { "justifyContent": "space-between", "alignItems": "center" } }, "boundingBox": [0, 0, 1440, 88], "childElements": [ { "elementType": "logo", /* ... */ }, { "elementType": "nav", /* ... */ }, { "elementType": "button", "displayName": "Sign Up", /* ... */ } ] }

几个要点:

  • elementType 是编程时的主键。API 识别数十种类型——header、button、input、card、badge、icon、tab、table、chart 等——在数百万真实 UI 上训练。
  • layoutConfig 捕捉子元素在父级内的排布。当检测器看到一排垂直居中、间距相近的元素,它会输出一个带 justifyContent 的 flex 行。自由定位元素得到 absolute。你拿到的是布局图,不是一堆框。
  • childElements 是递归的。整张图是以页面容器为根的一棵树,你可以深度遍历、渲染、比对或索引。
  • 文本 由多语言 OCR(50+ 种语言)处理,识别结果会落到正确容器里,而不是以悬空文本块出现。

如何衡量准确率与速度

实际元素匹配质量取决于界面类型、截图清晰度和结构复杂度。端到端延迟通常受分辨率、文本密度和队列状态影响；可用性以当前服务状态和适用协议为准。

边界框的"像素级"含义是:对比人工标注,视觉上清晰的元素 IoU 平均高于 0.9。紧凑布局中嵌套文本——六列数据表——偏差最大,这时每个元素上的 detectionScore 派上用场:在下游使用前过滤长尾低置信节点。

输出格式

默认响应是 JSON。同一端点族提供两种替代:

  • SVG —— 检测场景的矢量重绘。适合需要无损可编辑、且不绑定特定设计工具的场合。
  • Figma 兼容节点 —— 形状与 Figma 文件节点一致,可经 REST / 插件 API 直接塞入。Codia 的 Figma 插件消费的正是这种格式。

JSON 最灵活;SVG 和 Figma 格式都是围绕同一底层 Schema 的便利封装。

五件可做的事

1. 截图 → Figma 流水线。 拖一张图进插件，拿到完全可编辑的 Figma 文件。插件只是 API 的薄客户端。如果你在自家工具里做设计摄入，可以跳过插件直接调用 API。产品侧流程可以看：截图转 Figma。

2. 规模化视觉 QA。 与其在 CI 之间做像素级截图对比,不如对比它们的元素树。元素级 diff 忽略子像素渲染差异、字体回退和抗锯齿噪声,并给出人能读懂的 diff:"按钮 'Continue' 向右移动 12px,圆角新增 4px。"

3. AI 搜索的语义索引。 如果你在做"UI 版 Pinterest"——或者只是想让设计团队能搜索"带 sparkline 的暗色仪表盘"——Schema 提供了可查询结构。索引元素类型、颜色和文本内容,而不是原始图像。

4. 图像的无障碍 Lint。 截图本身不可访问;一棵带类型的元素树可以。把 JSON 丢进无障碍检查器,在以 PNG 形式落在工单里的设计上,就能发现缺失的 alt 文本、低对比度组合或未标注的按钮。

5. 基于截图的代码生成。 由于本 Schema 与我们的 PDF 与设计流水线共享语义,你可以直接把它导入 Codia 的代码生成器,产出 React、Vue、Flutter 或 HTML/Tailwind。描述图像的同一棵树,也生成了 UI。

Visual Struct 和 OCR 的区别

传统 OCR 只提取文字。Visual Struct 提取的是 UI 结构。如果你只需要图片里的文字，OCR 可能已经够用；如果你需要知道某段文字属于按钮、价格卡片、表格单元格还是导航项，就需要 Visual Struct。

这对设计自动化很关键。截图里有一个 "Continue" 文本意义有限；如果它是一个 button 节点，并且位于 checkout 表单里，旁边有输入框和错误提示，那它才真正可被程序使用。

边界情况处理

来自集成实战的几点建议:

  • 超长截图(比如整页营销站截图)最好在自然分段处切分。模型也处理 10k 像素高的图像,但分块能拿到更稳定的顶层分组。
  • 暗色模式 UI 受良好支持——检测器不依赖背景假设——但如果某张截图是明色设计的暗色渲染结果,提取到的颜色会反映屏幕像素,而非底层 token。
  • 手绘或草图级原型 可用,但 elementType 分布会偏向通用的 container 和 text,直到草图进一步收敛。
  • 多个嵌套可滚动区域(一个页面里含一个可滚动侧栏)会被扁平化为一棵树。模型不理解滚动,这层得由你自己建模。

快速上手

bash
curl 'https://api.codia.ai/v1/open/image_to_design' \ -H 'Authorization: Bearer {codia_api_key}' \ -H 'Content-Type: application/json' \ --data '{ "image_url": "https://example.com/ui.png" }'
  1. 在 codia.ai/dashboard/developer 获取 Key。
  2. 发送图片(URL 或 base64)。1440×900 的桌面截图是最佳尺寸。
  3. 遍历树。如果只关心高置信元素,先按 processingMeta.detectionScore > 0.6 过滤再用。
  4. 完整参考(Schema 定义、速率限制、错误码)在 /api。

如果你在考虑企业工作负载——本地、独立区域,或特定产品的自定义元素类型——请发邮件到 [email protected]。模型相同,交付方式不同。

UI 会继续以图像形式出现——在 bug 报告、Slack 聊天、Dribbble 作品、竞品研究里。把这些图像当作可查询结构,就能把原本只能人工完成的大量工作解锁出来。

FAQ

Visual Struct API 能把截图转成 Figma 吗？

可以。API 能返回 Figma 兼容节点，Codia Figma 插件也使用同一套底层结构来生成可编辑设计文件。

它和 OCR 一样吗？

不一样。OCR 主要提取文字；Visual Struct 会同时提取文字、布局、元素类型、层级和边界框。

什么尺寸的图片效果最好？

清晰的 1440 x 900 桌面截图或高分辨率移动端截图通常效果较好。超长网页建议按自然区块切分。

相关阅读

#visual-struct-api#screenshot-to-json#截图转json#screenshot-to-figma#ocr
← 返回文章列表