Visual Struct

概要

Visual Struct は UI スクリーンショットやモックアップを受け取り、含まれるすべての要素の階層的な JSON 記述を返します。各要素は型付き（header、button、card、table など）で、位置情報（ピクセル精度のバウンディングボックス）を持ち、親要素にリンクされているため、画像全体が1つのツリーとして表現されます。

スキーマは PDF to Visual Struct と共通であるため、ダウンストリームのコンシューマーは両方の入力を単一のコードパスで受け付けることができます。

エンドポイント

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

認証は Bearer トークンで行います。キーは codia.ai/dashboard/developer で取得してください。

リクエスト

フィールド	型	必須	説明
`image_url`	string	はい（`image_base64` と排他）	公開アクセス可能なソース画像の URL。
`image_base64`	string	はい（`image_url` と排他）	Base64 エンコードされた画像データ。
`output_format`	string	いいえ	`json`（デフォルト）、`svg`、または `figma`。

例

bash

curl 'https://api.codia.ai/v1/open/image_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --data '{ "image_url": "https://example.com/ui.png" }'

レスポンス

json

{
  "elementId": "header_section_001",
  "elementName": "HeaderSection",
  "elementType": "header",
  "displayName": "Header Section",
  "layoutConfig": {
    "positionMode": "flex",
    "flexibleMode": "row",
    "flexAttributes": {
      "justifyContent": "space-between",
      "alignItems": "center"
    }
  },
  "childElements": [ /* ネストされた要素 */ ]
}

フィールドリファレンス

フィールド	説明
`elementType`	要素クラス — `header`、`button`、`card`、`badge`、`icon`、`tab`、`table`、`chart` など。
`layoutConfig.positionMode`	`flex` または `absolute`。flex コンテナは `flexibleMode`（`row` / `column`）と `flexAttributes` を公開します。
`boundingBox`	ソース画像のピクセル座標での `[x, y, width, height]`。
`processingMeta.detectionScore`	0〜1 の信頼度。
`childElements`	子要素の再帰的配列。

出力フォーマット

フォーマット	ユースケース
`json`	デフォルト。カスタムのダウンストリームパイプラインに最適。
`svg`	検出されたシーンのロスレスなベクター再レンダリング。デザインツールに依存しません。
`figma`	REST API またはプラグイン経由で Figma ファイルに直接挿入できる形状のツリー。

3つのフォーマットすべてが同じ基盤スキーマから後処理されます。

性能

項目	値
要素マッチ精度	ベンチマークコーパスで 95% 以上
一般的なレイテンシ	画像あたり 2〜5 秒
OCR 対応言語	50 以上
最大画像サイズ	25 MB
推奨解像度	長辺 600〜4000 px
可用性	現在のサービス状態と適用契約に準拠

一般的なパターン

信頼度によるフィルタリング

function visibleElements(tree, threshold = 0.6) {
  const out = []
  const walk = (n) => {
    if ((n.processingMeta?.detectionScore ?? 1) >= threshold) {
      out.push(n)
      ;(n.childElements ?? []).forEach(walk)
    }
  }
  walk(tree)
  return out
}

長いスクリーンショット

全ページのマーケティングスクリーンショット（10,000 px 以上の高さ）は動作しますが、呼び出す前にセクション境界でチャンクすると、トップレベルのグルーピングがより安定します。

ダークモード UI

検出器は背景の仮定に依存しません。抽出されるカラーはレンダリング済みピクセルを反映します — セマンティックトークン（宣言されたブランドカラー、描画されたものではなく）が必要な場合は、独自のトークンシステムにマッピングしてください。

FAQ

多言語 UI はどう処理されますか？

OCR はテキストブロックごとに言語を検出するため、英語のコントロールと日本語の本文コピーを持つインターフェースは1回のリクエストで正しく処理されます。

API はアップロードされた画像を保持しますか？

画像はリクエストの完了とレスポンス URL の生成に必要な間のみ保持されます。エンタープライズデプロイメントでは保持期間をカスタマイズできます。

オンプレミスで実行できますか？

はい — 同じモデルがエンタープライズ向けに独立したコンテナとして提供されます。[email protected] までご連絡ください。

スクロール可能な領域はどう処理されますか？

API はフラットなツリーを返します。スクロールオーバーフローの概念はありません。既知の UI パターンまたは要素のオーバーフローに基づいて、独自にスクロールをアノテーションしてください。

次のステップ

PDF to Visual Struct — 同じスキーマ、PDF 入力。
Design to Code — スキーマをコード生成にパイプ。
完全なエンドポイントリファレンスは /api にあります。