PDF to Visual Struct

개요

PDF to Visual Struct는 PDF 페이지를 Codia의 Visual Element Schema로 변환합니다: 바운딩 박스, 레이아웃 설정, 스타일 사양을 갖춘 타입이 지정된 UI 요소의 계층적 JSON 트리입니다. Schema는 Codia Studio를 구동하는 것과 동일한 형식이므로, 다운스트림 소비자 — Figma 임포터, 코드 생성기, 시각적 QA 파이프라인 — 가 단일하고 안정적인 데이터 형태에 대해 작업할 수 있습니다.

Endpoint

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

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

요청

요청은 multipart/form-data 형식입니다.

필드	타입	필수	설명
`pdf_file`	file	예	변환할 PDF 파일. 요청당 하나의 파일.
`page_no`	string	예	변환할 0부터 시작하는 페이지 번호. 다중 페이지 변환은 클라이언트 측에서 루프하세요.

예시

bash

curl 'https://api.codia.ai/v1/open/pdf_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --form 'pdf_file=@"xx.pdf"' \
  --form 'page_no="0"'

응답

json

{
  "configuration": {
    "scalingFactor": 1,
    "baseWidth": 1940,
    "measurementUnit": "px"
  },
  "pages": [
    {
      "visualElement": { /* root element */ }
    }
  ],
  "size": {
    "height": 1080,
    "width": 1940
  }
}

최상위 필드

필드	설명
`configuration.baseWidth`	레이아웃 계산 시 사용되는 기준 너비. 다른 뷰포트 너비에서 렌더링할 때 이 값에 대해 바운딩 박스를 스케일링합니다.
`configuration.measurementUnit`	좌표 단위 — 일반적으로 `px`.
`configuration.scalingFactor`	사전 적용된 스케일링 팩터. 보통 `1`.
`size.width`, `size.height`	기본 좌표계에서 계산된 페이지 캔버스.
`pages[].visualElement`	페이지 트리의 루트 요소. `childElements`를 재귀적으로 탐색합니다.

Visual Element Schema

트리의 각 노드는 동일한 형태를 가집니다:

json

{
  "elementId": "pdf_page_1",
  "elementName": "PDF Document Page",
  "elementType": "Panel",
  "displayName": "First Page",
  "displayOrder": 0,
  "boundingBox": [0, 0, 595, 842],
  "layoutConfig": {
    "positionMode": "Normal",
    "flexibleMode": "Absolute"
  },
  "styleConfig": {
    "widthSpec":  { "sizing": "FIXED", "value": 595 },
    "heightSpec": { "sizing": "FIXED", "value": 842 },
    "backgroundSpec": {
      "type": "COLOR",
      "backgroundColor": { "rgbValues": [255, 255, 255] }
    }
  },
  "processingMeta": {
    "surfaceArea": 501490,
    "detectionScore": 0.92,
    "textContainerized": false
  },
  "childElements": []
}

필드 레퍼런스

필드	설명
`elementId`	이 응답 내에서의 안정적인 식별자. 페이지 간 전역 고유가 아닙니다.
`elementType`	타입이 지정된 요소 클래스: `Panel`, `Text`, `Image`, `Icon`, `Button`, `Table`, `Chart` 등 50가지 이상.
`boundingBox`	기본 좌표에서 `[x, y, width, height]`.
`layoutConfig.positionMode`	`Normal`(플로우) 또는 `Absolute`.
`layoutConfig.flexibleMode`	`Row`, `Column`, 또는 `Absolute` — Figma 오토 레이아웃 시맨틱을 반영합니다.
`styleConfig.widthSpec.sizing`	`FIXED`, `FILL_CONTAINER`, 또는 `HUG_CONTENT`.
`styleConfig.backgroundSpec`	배경 페인트 — 색상, 그라데이션, 또는 이미지.
`processingMeta.detectionScore`	감지기 신뢰도, `0.0` – `1.0`. 다운스트림에서 사용하기 전에 낮은 신뢰도 노드를 필터링합니다.
`childElements`	자식 Visual Element 배열. 깊이 우선 탐색으로 전체 계층 구조를 확인합니다.

제한 사항

설정	기본값
최대 파일 크기	50 MB
문서당 최대 페이지	100
분당 최대 요청 수	플랜에 따라 다름 — 가격 참조.
페이지당 일반적인 지연 시간	600 ms – 2 s

지원되는 입력

텍스트 네이티브 PDF(디자인 도구, 오피스 제품군, 프로그래매틱 생성) — 가장 높은 충실도.
스캔된 PDF — OCR이 자동으로 적용됩니다; 저해상도 스캔에서는 더 많은 노이즈가 예상됩니다.
비밀번호로 보호된 PDF는 지원되지 않습니다. 업로드 전에 잠금을 해제하세요.

일반적인 패턴

다중 페이지 변환

플랜의 동시성 제한까지 page_no를 0부터 문서 길이까지 병렬로 루프합니다:

const pages = await Promise.all(
  pageNumbers.map((n) => fetch(ENDPOINT, buildRequest(file, n))),
)

낮은 신뢰도 노드 필터링

function prune(node, minScore = 0.6) {
  node.childElements = (node.childElements || [])
    .filter((c) => c.processingMeta.detectionScore >= minScore)
    .map((c) => prune(c, minScore))
  return node
}

Figma 왕복 변환

layoutConfig가 Figma 오토 레이아웃을 반영하므로, 트리를 오토 레이아웃 프레임으로 직접 임포트할 수 있습니다. 임포터를 직접 구축하고 싶지 않다면 PDF to Design Figma 플러그인을 사용하세요.

FAQ

한 번의 호출로 모든 페이지를 변환할 수 있나요?

단일 호출로는 불가능합니다 — endpoint는 페이지 단위입니다. 클라이언트 측에서 루프와 병렬화를 수행하세요.

변환 정확도는 어떤가요?

실제 인식 품질은 PDF 원본, 텍스트 선명도, 구조 복잡도에 따라 달라집니다. 스캔된 법률 양식과 수기 주석 입력은 더 낮을 수 있으므로 항상 processingMeta.detectionScore를 확인하세요.

폰트가 보존되나요?

폰트 이름, 크기, 두께, 색상이 styleConfig에 보존됩니다. 보존된 폰트를 렌더링하려면 출력을 사용하는 곳에 해당 폰트가 설치되어 있어야 합니다.

SDK가 있나요?

SDK는 필요하지 않습니다 — API는 순수 HTTP + JSON입니다. 공식 SDK는 로드맵에 있습니다.

온프레미스 배포가 가능한가요?

네, 엔터프라이즈 플랜에서 가능합니다. [email protected]로 연락하세요.

다음 단계

Visual Struct — 동일한 Schema, 이미지 입력.
Remove BG — 렌더링된 출력에 합성하기 위한 투명 배경 이미지.
전체 endpoint 레퍼런스는 /api#convert-pdf-to-design에서 확인하세요.