**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 الموقّعة مسبقًا أو روابط 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 ذات صلة