**Cost**: 13 credits per successful call.

Turn a single UI screenshot into an editable, hierarchical design tree — the same representation Codia Studio uses internally and the foundation that downstream code-generation, Figma-import, and layer-decomposition workflows are built on.

## Request options

This endpoint supports two input modes:

1. **JSON URL mode**: send `application/json` with `image_url` when the image is already publicly reachable.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

JSON example:

```bash
curl 'https://openapi.codia.ai/v2/open/image_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --data '{ "image_url": "https://example.com/screenshot.png" }'
```

Direct upload example:

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

## What this API is for

Given a public image URL of a UI (mobile screen, desktop page, dashboard, marketing hero — anything pixel-based), the service runs detection + layout reconstruction and returns a tree of **`VisualElement`** nodes that mirror how a designer would have built the screen in Figma or Sketch:

- Every visible region becomes a node with a position, a size, and a style.
- Container/child relationships are preserved (e.g. a card holds its title, body, and CTA).
- Layout intent (Flex vs. Absolute), text typography (font, size, weight, color), shapes, images, and effects are all reified into structured fields — not flattened into a single bitmap.

Typical use cases:
- **Image → code / image → Figma**: walk the tree and emit React / HTML / Figma nodes.
- **Design QA**: diff a screenshot against a spec by comparing structured trees.
- **Layer extraction**: feed the tree into downstream tools (e.g. our PDF/PPT pipeline or your own renderer).
- **Agent / LLM workflows**: give a model a structured layout instead of raw pixels so it can reason about "the price label sits inside the product card."

## How the response is shaped

The response uses the standard Codia envelope (`code`, `message`, `data`). On success `code = 0` and `data` contains two fields:

| Field | What it is | How to use it |
|---|---|---|
| `data.configuration` | Global rendering settings — `baseWidth`, `measurementUnit` (`px` \| `pt`), `scalingFactor`. | Multiply every numeric value in the tree by `scalingFactor` when rendering. Treat `baseWidth` as the canvas width the tree was measured against (375 for mobile, 1440 for desktop, etc.). |
| `data.visualElement` | The **root** of the visual tree. Always an `elementType: "Body"` node whose `childElements` recursively contain the rest of the page. | Traverse depth-first. The fields you care about per node depend on `elementType` (see below). |

## Walking the `VisualElement` tree

Each node has the same shape, but a handful of fields are populated based on `elementType`:

| `elementType` | Populated content fields | Typical meaning |
|---|---|---|
| `Body` | `layoutConfig`, `styleConfig` | Root of the page / artboard |
| `Layer` | `layoutConfig`, `styleConfig` | Generic container (card, section) |
| `Group` | `childElements` | Pure grouping, no own visuals |
| `Text` | `styleConfig.textConfig`, `contentData.textValue` | A run of text |
| `Image` | `contentData.imageSource` | Raster image (URL) |
| `Vector` | `contentData.vectorData` | Vector shape (mostly PDF; image_to_design uses `Image` / `Layer` for shapes) |
| `Component` | `componentSpec`, `contentData.componentReference` | Reusable detected component |

For every node:
- **`elementId` / `elementName`** — stable identifier + human label. Use `elementId` as your React `key` or Figma node id.
- **`childElements`** — array of nested `VisualElement`s. Empty leaf for text/image. Recurse here.
- **`processingMeta.detectionScore`** — confidence in `[0, 1]`. Filter or warn on low-confidence nodes when generating production code.
- **`processingMeta.surfaceArea`** — pixel area; useful for sorting or pruning tiny artifacts.

### `layoutConfig` — where the node sits

- `positionMode`:
  - `"Flex"` — the node participates in its parent's flex layout. Read `flexAttributes` (`flexDirection`, `alignItems`, `justifyContent`, `flexWrap`) on the **parent** to know how children flow.
  - `"Absolute"` — positioned at exact coordinates. Read `absoluteAttrs.coord` for the offset relative to the parent.
  - `"Normal"` / `"Relative"` — document-flow positioning (rare on this endpoint; common at the root).
- `flexibleMode` — present on containers, identifies the flex variant the detector chose.

In practice, the root `Body` is `Flex` and most children inherit Flex from their parent, so a naive emitter that maps `positionMode` → CSS `display: flex` + `position: absolute` will reproduce the layout faithfully.

### `styleConfig` — what the node looks like

This is the largest object in the response. Group the fields by what they describe:

- **Size** — `widthSpec`, `heightSpec`. Each is a `DimensionSpec` with `sizing` (`FIXED` = exact px, `FILL` = stretch to parent, `FIT_CONTENT` = shrink to children) and a numeric `value`. Map `FIXED → width: Npx`, `FILL → flex: 1` (or `width: 100%`), `FIT_CONTENT → width: auto`.
- **Text** (on `Text` nodes) — `textConfig.{fontSize, fontStyle, fontFamily, lineHeight, letterSpacing, textAlign}` + `textColor` (a `VisualColor` with `rgbValues` and `hexCode`). `letterSpacing` is in CSS px against the detected font-size; Studio converts to a percentage at import time (Figma semantics).
- **Border** — `borderConfig.{borderWidth, borderStyle, borderColor, borderRadius}`. `borderRadius` is an array `[tl, tr, br, bl]`; collapse to a single value if all four are equal.
- **Background** — `backgroundConfig` is a `oneOf` with three shapes discriminated by `type`:
  - `"COLOR"` → solid fill via `backgroundColor`.
  - `"IMAGE"` → `imageUrl` + CSS-style `backgroundSize` / `backgroundPosition`.
  - `"LINEAR_GRADIENT"` → `deg` + `gradientStops[]` (each stop = `{color, position}` where `position` is 0–1).
- **Effects / transforms** — `effectsList` (shadows, blurs), `opacityLevel` (0–255 — divide by 255 for CSS), `rotationAngle` (degrees), `paddingValues`, `overflowMode`.

Fields tagged "PDF only" in the schema (`characterData`, `transformMatrix`, `cornerRadius`, `isRightToLeft`, `extendedMatrix`) are not produced by image_to_design — they're shared with `pdf_to_design` and you can ignore them here. Same for `boundingBox`, `displayOrder`, and `contentData.{svgTemplate, imageData, maskingMode, blendingType}`.

### `contentData` — what the node displays

Only populated on leaf-ish nodes:
- `textValue` — the actual string for `Text` nodes.
- `imageSource` — public URL for `Image` nodes (re-hosted on Codia's CDN; safe to embed).
- `componentReference` / `componentAttributes` — pointer + props for detected components, paired with `componentSpec` on the same node.

## A minimal traversal

```ts
function walk(node: VisualElement, depth = 0) {
  console.log('  '.repeat(depth), node.elementType, node.elementId,
    node.elementType === 'Text' ? node.contentData?.textValue :
    node.elementType === 'Image' ? node.contentData?.imageSource : '');
  node.childElements?.forEach(child => walk(child, depth + 1));
}
walk(response.data.visualElement);
```

## Inputs, limits, billing

- **Input** — either JSON with a single `image_url` pointing to a publicly fetchable PNG / JPG / WebP, or `multipart/form-data` with an `image` file. For direct upload, Codia checks credits before reading and uploading the file. Field name `file` is also accepted for compatibility. Maximum side length and file-size limits follow the global Codia API limits.
- **Billing** — consumes the unified Codia Open API balance (see `GET /v2/open/credits`). 13 credits per successful call.
- **Latency** — synchronous; typical end-to-end is single-digit seconds for mobile screens, longer for dense desktop pages.
- **Idempotency** — same image URL produces the same tree modulo `elementId` regeneration; do not rely on stable IDs across calls.

## Errors

Uses the standard envelope with non-zero `code` and a descriptive `message`. HTTP status codes:
- `400` — bad input (missing/invalid `image_url`, unreachable URL, unsupported MIME).
- `401` / `403` — missing / wrong / unauthorized API key.
- `402` — credit balance exhausted (top up via the dashboard or `/v2/open/auto_recharge`).
- `429` — rate-limited; back off and retry.
- `500` — internal error; safe to retry once.

### `measurementUnit`

Always `px` for `image_to_design` — screen captures and rasterised UI are inherently pixel-based.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_to_design` instead. Inputs and credit cost are identical to this v2 endpoint.

사용자가 지정하는 선택적 키(최대 255자). 설정하면 성공한(2xx) 응답이 7일 동안 캐시됩니다. 같은 키와 동일한 요청 본문으로 재시도하면 캐시된 응답이 반환되며 크레딧이 추가로 차감되지 않습니다. 같은 키로 다른 본문을 보내면 409가 반환됩니다. 네트워크 장애 시 POST를 안전하게 재시도할 수 있도록 하려면 이 키를 사용합니다. multipart/form-data 업로드는 폼 필드와 파일 내용으로 요청을 비교하므로, 클라이언트가 새 multipart boundary를 선택하더라도 재시도한 업로드에도 캐시된 응답이 반환됩니다.

Idempotency-Key

분석할 이미지의 공개 URL. 직접 가져올 수 있는 PNG, JPG 또는 WebP여야 합니다. 사전 서명된 S3 URL이나 CDN URL은 사용할 수 있지만, 로그인이나 JavaScript 뒤에서 에셋을 제공하는 페이지는 실패합니다. 별도의 `image_base64` 필드는 없으므로 먼저 이미지를 호스팅하십시오.

image_url

분석할 로컬 이미지 파일. 이미지가 아직 호스팅되지 않은 경우에 사용합니다. 서버는 파일을 읽고 업로드하기 전에 크레딧을 확인합니다. 호환성을 위해 필드 이름 `file`도 허용됩니다.

image

변환에 성공했습니다. `data.visualElement`는 트리의 루트인 `Body` 노드입니다. `childElements`를 재귀적으로 탐색하면 감지된 모든 영역에 도달할 수 있습니다. `data.configuration`에는 캔버스 기준 너비, 단위, 스케일 계수가 담겨 있으며, 렌더링 전에 모든 숫자 값에 이 스케일 계수를 곱해야 합니다. `elementType`, `layoutConfig`, `styleConfig`, `contentData`에 대한 자세한 설명은 위의 작업 설명을 참고하십시오.

성공 시 0입니다. 0이 아닌 값은 HTTP 상태 코드 계열(400/401/402/403/429/500)에 대응합니다.

code

사람이 읽을 수 있는 상태. 성공 시 `"ok"`이며, 그 외에는 오류 사유입니다.

message

디자인 트리의 루트. 항상 `elementType: "Body"`입니다. 이 노드의 `childElements`가 페이지의 나머지 부분을 구성합니다.

visualElement

트리 측정의 기준이 된 캔버스 수준의 렌더링 설정. 렌더링 시 모든 숫자 값에 `scalingFactor`를 적용하십시오.

configuration

data

요청 본문의 형식이 잘못되었거나 필수 매개변수가 누락되었습니다

API 키가 없거나, 유효하지 않거나, 폐기되었습니다

계정 잔액이 부족하거나 구독이 만료되었습니다

계정에 이 엔드포인트에 대한 액세스 권한이 없습니다

Idempotency-Key가 다른 요청 본문과 함께 재사용되었습니다.

속도 제한에 도달했습니다. `Retry-After` 헤더에 표시된 초만큼 기다린 후 재시도하십시오.

서버에서 예기치 않은 오류가 발생했습니다

Background

Add to bag

Image

Vitamin C and hyaluronic acid brighten a

Vitamin C and hyaluronic acid brighten and hydrate.
Lightweight, fragrance-free, for all skin types.

Refill

50 ml

30 ml

$49.00

$34.30

4.8 · 1,284 reviews

Glow Serum 30 ml

VELORA SKINCARE

-30%

Product

9:41

UI 스크린샷을 편집 가능한 레이어 구조의 디자인 트리로 변환합니다. Codia Studio와 동일한 구조로, 컨테이너, 텍스트, 이미지, 도형과 각각의 스타일을 포함합니다.

이미지를 디자인으로

입력

출력

관련 API