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

Optionaler, vom Client festgelegter Schlüssel (bis zu 255 Zeichen). Ist er gesetzt, wird eine erfolgreiche (2xx) Antwort 7 Tage lang zwischengespeichert. Eine Wiederholung mit demselben Schlüssel und identischem Request-Body liefert die gespeicherte Antwort (ohne zusätzliche Credits); eine Wiederholung mit demselben Schlüssel, aber anderem Body liefert 409. Damit lassen sich POST-Requests bei Netzwerkfehlern gefahrlos wiederholen. Bei multipart/form-data-Uploads werden Requests anhand der Formularfelder und Dateiinhalte verglichen, sodass ein wiederholter Upload auch dann als Wiederholung erkannt wird, wenn der Client eine neue Multipart-Boundary wählt.

Idempotency-Key

Öffentliche URL des zu analysierenden Bildes. Muss ein direkt abrufbares PNG, JPG oder WebP sein — vorsignierte S3- oder CDN-URLs funktionieren, Seiten, die das Asset hinter einem Login oder JavaScript verbergen, dagegen nicht. Es gibt kein separates Feld `image_base64`; hosten Sie das Bild zuerst.

image_url

Lokale Bilddatei zur Analyse. Verwenden Sie dieses Feld, wenn das Bild noch nicht gehostet ist. Der Server prüft die Credits, bevor er die Datei liest und hochlädt. Aus Kompatibilitätsgründen wird auch der Feldname `file` akzeptiert.

image

Erfolgreiche Konvertierung. `data.visualElement` ist der Wurzelknoten `Body` des Baums — durchlaufen Sie `childElements` rekursiv, um jede erkannte Region zu erreichen. `data.configuration` enthält die Basisbreite der Zeichenfläche, die Einheit und einen Skalierungsfaktor, mit dem Sie vor dem Rendern jeden numerischen Wert multiplizieren sollten. Eine ausführliche Erläuterung von `elementType`, `layoutConfig`, `styleConfig` und `contentData` finden Sie in der Beschreibung der Operation oben.

0 bei Erfolg; Werte ungleich 0 entsprechen der HTTP-Statusklasse (400/401/402/403/429/500).

code

Menschenlesbarer Status. `"ok"` bei Erfolg, andernfalls ein Fehlergrund.

message

Wurzel des Design-Baums. Immer `elementType: "Body"`. Seine `childElements` bilden den Rest der Seite.

visualElement

Rendering-Einstellungen auf Ebene der Zeichenfläche, auf die sich die Maße des Baums beziehen. Wenden Sie `scalingFactor` beim Rendern auf jeden numerischen Wert an.

configuration

data

Der Request-Body ist fehlerhaft oder es fehlen erforderliche Parameter

Der API-Schlüssel fehlt, ist ungültig oder wurde widerrufen

Das Kontoguthaben reicht nicht aus oder das Abonnement ist abgelaufen

Das Konto hat keinen Zugriff auf diesen Endpunkt

Idempotency-Key mit einem anderen Request-Body wiederverwendet.

Rate-Limit erreicht. Warten Sie vor einem erneuten Versuch die im Header `Retry-After` angegebene Anzahl an Sekunden.

Auf dem Server ist ein unerwarteter Fehler aufgetreten

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

Wandelt einen UI-Screenshot in einen bearbeitbaren Design-Baum mit Ebenen um: dieselbe Struktur, die Codia Studio verwendet, mit Containern, Text, Bildern, Formen und deren Stilen.

Bild zu Design

Eingabe

Ausgabe

Ähnliche APIs