Visual Struct

개요

Visual Struct는 UI 스크린샷 또는 목업을 받아 포함된 모든 요소의 계층적 JSON 설명을 반환합니다. 각 요소는 타입이 지정되고(header, button, card, table 등), 위치가 지정되며(픽셀 정확한 바운딩 박스), 부모에 연결되어 전체 이미지가 하나의 트리로 표현됩니다.

Schema는 PDF to Visual Struct와 공유되므로, 다운스트림 소비자가 단일 코드 경로를 통해 두 입력을 모두 처리할 수 있습니다.

Endpoint

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

인증은 bearer 토큰으로 수행합니다. codia.ai/dashboard/developer에서 키를 받으세요.

요청

필드	타입	필수	설명
`image_url`	string	예 (`image_base64`와 택일)	공개적으로 접근 가능한 소스 이미지 URL.
`image_base64`	string	예 (`image_url`와 택일)	Base64로 인코딩된 이미지 데이터.
`output_format`	string	아니오	`json`(기본값), `svg`, 또는 `figma`.

예시

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

응답

json

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

필드 레퍼런스

필드	설명
`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
}

긴 스크린샷

전체 페이지 마케팅 스크린샷(10,000+ 픽셀 높이)도 작동하지만, 호출 전에 섹션 경계에서 청킹하면 더 안정적인 최상위 그룹핑을 얻을 수 있습니다.

다크 모드 UI

감지기는 배경에 대한 가정에 의존하지 않습니다. 추출된 색상은 렌더링된 픽셀을 반영합니다 — 시맨틱 토큰(선언된 브랜드 색상, 페인팅된 것이 아닌)이 필요하면 여러분 쪽에서 토큰 시스템에 매핑하세요.

FAQ

다국어 UI는 어떻게 처리되나요?

OCR은 텍스트 블록별로 언어를 감지하므로, 영어 컨트롤과 일본어 본문 텍스트가 있는 인터페이스도 단일 요청에서 올바르게 처리됩니다.

API가 업로드된 이미지를 보관하나요?

이미지는 요청을 완료하고 응답 URL을 생성하는 데 필요한 시간만큼만 보관됩니다. 엔터프라이즈 배포에서는 보관 기간을 커스터마이징할 수 있습니다.

온프레미스에서 실행할 수 있나요?

네 — 동일한 모델이 엔터프라이즈용 격리된 컨테이너로 제공됩니다. [email protected]로 연락하세요.

스크롤 가능한 영역은 어떻게 처리하나요?

API는 플랫 트리를 반환하며, 스크롤 오버플로우 개념이 없습니다. 알려진 UI 패턴이나 요소 오버플로우를 기반으로 여러분 쪽에서 스크롤을 주석 처리하세요.

다음 단계

PDF to Visual Struct — 동일한 Schema, PDF 입력.
Design to Code — Schema를 코드 생성에 연결합니다.
전체 endpoint 레퍼런스는 /api에서 확인하세요.