Codia
← 글 목록으로 돌아가기

스크린샷에서 구조로: Visual Struct API로 구축하기

Engineering2026-04-23

"구조"가 중요한 이유

UI 스크린샷은 컴퓨터에게 픽셀의 격자입니다. 하지만 디자이너나 개발자에게는 제목, 가격, 평점, 버튼이 있는 카드입니다. 이 두 관점을 연결하는 것 — 픽셀을 이름과 타입이 지정된 요소의 트리로 변환하는 것 — 이 바로 Visual Struct API가 하는 일입니다.

이미지를 보내세요. 포함된 모든 UI 요소의 계층적 JSON 설명을 돌려받습니다. 각 요소에는 타입, 바운딩 박스, 텍스트 콘텐츠, 부모와의 레이아웃 관계가 포함됩니다. 그것이 전부입니다. 프롬프트 엔지니어링도, 수동 라벨링도, 여러분 쪽에서 컴퓨터 비전 보일러플레이트도 필요 없습니다.

팀들이 이 출력을 사용하여 경쟁사 스크린샷을 Figma로 자동 임포트하고, 모바일 앱의 시각적 회귀 테스트를 수행하고, AI 검색을 위해 스크린샷을 인덱싱하고, Dribbble 샷에서 직접 코드를 생성하는 것을 보았습니다. 이 글은 API가 실제로 반환하는 것과 그것을 기반으로 구축하는 방법에 대한 내용입니다.

응답의 형태

모든 요소는 동일한 핵심 필드를 가집니다. 다음은 랜딩 페이지 스크린샷에서 잘라낸 헤더입니다:

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 이상이라는 의미에서 픽셀 정확합니다. 밀접한 레이아웃 내 중첩된 텍스트 — 6열 데이터 표를 생각해 보세요 — 에서 가장 큰 편차를 볼 수 있으며, 이때 각 요소의 detectionScore가 그 가치를 발휘합니다: 다운스트림에서 사용하기 전에 낮은 신뢰도 노드의 롱 테일을 필터링하세요.

출력 형식

기본 응답은 JSON입니다. 동일한 endpoint 패밀리에서 두 가지 대안 형식을 사용할 수 있습니다:

  • SVG — 감지된 장면의 벡터 재렌더링. 특정 디자인 도구에 종속되지 않는 무손실 편집 가능한 버전의 스크린샷이 필요할 때 유용합니다.
  • Figma 호환 노드 — REST 또는 플러그인 API를 통해 Figma 파일에 직접 삽입할 수 있도록 구성된 트리. Codia Figma 플러그인이 사용하는 형식입니다.

JSON 버전이 가장 유연합니다; SVG와 Figma 출력은 동일한 기본 Schema를 후처리하는 편의 래퍼입니다.

구축할 수 있는 다섯 가지

1. 스크린샷 → Figma 파이프라인. 아마 이것을 본 적이 있을 것입니다: 이미지를 플러그인에 드롭하면 완전히 편집 가능한 Figma 파일을 얻습니다. 플러그인은 API 위의 얇은 클라이언트입니다. 자체 도구 내에서 디자인 수집을 한다면 플러그인을 건너뛰고 API를 직접 호출하세요.

2. 대규모 시각적 QA. CI 실행 간 스크린샷을 픽셀 비교하는 대신 요소 트리를 비교하세요. 요소 수준 비교는 서브픽셀 렌더링 차이, 폰트 대체, 안티앨리어싱 노이즈를 무시하며, 사람이 실제로 읽을 수 있는 차이를 제공합니다: "버튼 'Continue'가 12px 오른쪽으로 이동, 4px border-radius 추가."

3. AI 검색을 위한 시맨틱 인덱싱. Pinterest 같은 UI 제품을 구축하고 있거나 — 또는 디자인 팀이 "스파크라인이 있는 다크모드 대시보드"를 검색하길 원한다면 — Schema가 쿼리 가능한 구조를 제공합니다. 원시 이미지 대신 요소 유형, 색상, 텍스트 콘텐츠를 인덱싱하세요.

4. 이미지에 대한 접근성 린트. 스크린샷은 접근성이 없습니다; 타입이 지정된 요소의 트리는 접근 가능합니다. JSON을 접근성 검사기에 전달하여 티켓에 PNG로 존재하는 디자인에서 누락된 대체 텍스트, 낮은 대비 조합, 또는 라벨이 없는 버튼을 발견하세요.

5. 스크린샷에서 코드 생성. Schema가 PDF 및 디자인 파이프라인과 시맨틱을 공유하므로 Codia의 코드 생성기에 바로 전달하여 React, Vue, Flutter 또는 HTML/Tailwind를 생성할 수 있습니다. 이미지를 설명하는 동일한 트리가 UI도 생성합니다.

엣지 케이스 처리

통합에서 얻은 몇 가지 실용적인 참고 사항:

  • 매우 긴 스크린샷(마케팅 사이트의 전체 페이지 캡처 등)은 자연스러운 섹션 경계에서 분할하는 것이 좋습니다. 모델은 10,000픽셀 높이의 이미지에서도 작동하지만, 청킹하면 더 안정적인 그룹핑을 얻을 수 있습니다.
  • 다크 모드 UI는 잘 지원됩니다 — 감지기는 배경에 대한 가정에 의존하지 않습니다 — 하지만 스크린샷이 라이트 모드 디자인의 렌더링된 다크 테마인 경우, 추출된 색상은 토큰 값이 아니라 화면에 보이는 것을 반영합니다.
  • 손으로 그린 또는 스케치 수준의 목업도 작동하지만, 스케치가 정교해질 때까지 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에서 키를 받으세요.
  2. 이미지를 보내세요(URL 또는 base64). 1440x900 데스크톱 스크린샷이 가장 적합합니다.
  3. 트리를 탐색하세요. 신뢰도 임계값 이상의 요소만 원한다면 processingMeta.detectionScore > 0.6으로 사전 필터링하여 노이즈를 건너뛰세요.
  4. 전체 레퍼런스 — Schema 정의, 레이트 리밋, 에러 코드 — 는 /api에 있습니다.

엔터프라이즈 워크로드를 고려하고 있다면 — 온프레미스, 프라이빗 리전, 또는 제품에 특화된 커스텀 요소 유형 — [email protected]가 적합한 창구입니다. 모델은 동일합니다; 패키징만 달라집니다.

UI는 계속 이미지로 캡처될 것입니다 — 버그 리포트에서, Slack 스레드에서, Dribbble 샷에서, 경쟁사 리서치에서. 그 이미지를 쿼리 가능한 구조로 취급하면 이전에 수작업으로 해야 했던 많은 작업이 열립니다.

#visual-struct#api#computer-vision#ocr#design-tooling
← 글 목록으로 돌아가기