Visual Struct

概览

Visual Struct 接收一张 UI 截图或 mockup,返回其中每个元素的层级 JSON 描述。每个元素都有类型(header、button、card、table 等)、定位(像素精度的边界框),并与父节点建立层级,把整张图像表示为一棵树。

该 Schema 与 PDF to Visual Struct 共享,下游可用同一代码路径消费两种输入。

端点

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

通过 Bearer Token 鉴权。在 codia.ai/dashboard/developer 获取 Key。

请求方式

二选一即可：

模式	Content-Type	必填字段	说明
JSON URL	`application/json`	`image_url`	可公开访问的源图像 URL。
直接上传	`multipart/form-data`	`image`	本地图片文件。为兼容也接受字段名 `file`。

示例

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" }'

也可以直接上传本地文件：

bash

curl 'https://api.codia.ai/v1/open/image_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./screenshot.png'

Codia 会先校验 credits，再读取并上传 multipart 文件。余额不足时直接返回 402，不会上传文件。

响应

json

{
  "elementId": "header_section_001",
  "elementName": "HeaderSection",
  "elementType": "header",
  "displayName": "Header Section",
  "layoutConfig": {
    "positionMode": "flex",
    "flexibleMode": "row",
    "flexAttributes": {
      "justifyContent": "space-between",
      "alignItems": "center"
    }
  },
  "childElements": [ /* 嵌套元素 */ ]
}

字段参考

字段	说明
`elementType`	元素类:`header`、`button`、`card`、`badge`、`icon`、`tab`、`table`、`chart` 等。
`layoutConfig.positionMode`	`flex` 或 `absolute`。Flex 容器暴露 `flexibleMode`(`row`/`column`)和 `flexAttributes`。
`boundingBox`	源图像像素坐标下的 `[x, y, width, height]`。
`processingMeta.detectionScore`	0–1 置信度。
`childElements`	递归的子元素数组。

输出格式

格式	用途
`json`	默认,最适合自定义下游流水线。
`svg`	无损矢量重绘,与设计工具无关。
`figma`	可通过 REST / 插件 API 直接插入 Figma 的节点结构。

三种格式都由同一底层 Schema 后处理而来。

能力

能力	数值
元素匹配质量	取决于源文件清晰度与结构复杂度
典型延迟	2–5 秒 / 图
OCR 语言	50+
单图大小上限	25 MB
推荐分辨率	长边 600–4000 px
可用性	以当前服务状态和适用协议为准

常见模式

按置信度过滤

function visibleElements(tree, threshold = 0.6) {
  const out = []
  const walk = (n) => {
    if ((n.processingMeta?.detectionScore ?? 1) >= threshold) {
      out.push(n)
      ;(n.childElements ?? []).forEach(walk)
    }
  }
  walk(tree)
  return out
}

超长截图

整页营销站截图(10k+ 像素高)可工作,但在调用前按自然分段切分能得到更稳定的顶层分组。

暗色 UI

检测器不依赖背景假设。提取到的颜色反映屏幕像素——若你需要语义 token(设计时的品牌色而非显示色),请在消费端映射回你的 token 系统。

常见问题

混合语言 UI 如何处理?

OCR 按文本块检测语言,因此英文控件配日文正文能在一次请求内被正确处理。

API 会保存上传的图片吗?

仅在完成请求、生成响应 URL 所需的时间内保留。企业部署可自定义保留期。

能私有化部署吗?

可以。同一模型以隔离容器交付企业。请联系 [email protected]。

如何处理可滚动区域?

API 返回扁平的树,无滚动溢出概念。请基于已知 UI 模式或元素溢出在你这端标注。

下一步

PDF to Visual Struct —— 同 Schema,PDF 输入。
Design to Code —— 将 Schema 接入代码生成。
完整端点参考:/api。