**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.

Idempotency-Key

Публичный URL анализируемого изображения. По нему должен напрямую отдаваться PNG, JPG или WebP — предподписанные URL S3 или CDN подходят, а страницы, закрывающие файл авторизацией или JavaScript, не сработают. Отдельного поля `image_base64` нет; сначала разместите изображение на хостинге.

image_url

Локальный файл изображения для анализа. Используйте это поле, если изображение ещё не размещено в сети. Сервер проверяет кредиты до чтения и загрузки файла. Для совместимости также принимается имя поля `file`.

image

Успешная конвертация. `data.visualElement` — корневой узел `Body` дерева; рекурсивно обходите `childElements`, чтобы добраться до каждой обнаруженной области. `data.configuration` содержит базовую ширину холста, единицу измерения и коэффициент масштабирования, на который нужно умножать каждое числовое значение перед отрисовкой. Подробное описание `elementType`, `layoutConfig`, `styleConfig` и `contentData` см. в описании операции выше.

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

Преобразует скриншот интерфейса в редактируемое многослойное дерево дизайна — ту же структуру, что использует Codia Studio: контейнеры, текст, изображения, фигуры и их стили.

Изображение в дизайн

Входные данные

Выходные данные

Похожие API