スクリーンショットから構造へ：Visual Struct API を使った開発

「構造」こそが重要な単位である理由

UI のスクリーンショットは、コンピュータにとってはピクセルのグリッドに過ぎません。しかし人間のデザイナーや開発者にとっては、見出し、価格、評価、ボタンを持つカードです。この2つの見方を橋渡しすること — ピクセルを名前と型を持つ要素のツリーに変換すること — が Visual Struct API の役割です。

画像を送信すると、含まれるすべての UI 要素の階層的な JSON 記述が返されます。各要素には型、バウンディングボックス、テキスト内容、親要素とのレイアウト関係が付与されます。それだけです。プロンプトエンジニアリングも、手動ラベリングも、クライアント側のコンピュータビジョンのボイラープレートも不要です。

競合のスクリーンショットを Figma に自動インポートする、モバイルアプリのビジュアルリグレッションスイートを駆動する、AI 検索用にスクリーンショットをインデックスする、Dribbble のショットからコードを直接生成するなど、さまざまな用途で活用されています。この記事では、API が実際に何を返すか、そしてその上にどう構築するかについて解説します。

レスポンスの形状

すべての要素は同じコアフィールドを持ちます。以下はランディングページのスクリーンショットから切り取ったヘッダーの例です：

注目すべきポイント：

• elementType はプログラムで処理する際の主キーです。API は数十種類の型を認識します — header、button、input、card、badge、icon、tab、table、chart など — この型セットは数百万の実際の UI に対してトレーニングされています。
• layoutConfig は子要素が親内部でどのように配置されるかを捉えます。検出器が垂直方向の中心が揃い、間隔が均等な要素の行を検出すると、適切な justifyContent を持つ flex row を出力します。自由配置の要素は absolute になります。単なるボックスの集合ではなく、レイアウトグラフが得られます。
• childElements は再帰的です。画像全体がページコンテナをルートとする単一のツリーであり、深さ優先で走査してレンダリング、差分比較、インデックス作成が可能です。
• テキスト は多言語 OCR ステージで処理されます — 50以上の言語に対応 — 認識された文字列はフローティングテキストランではなく、正しいコンテナ内に配置されます。

精度と速度の測定方法

実際の要素マッチ品質は、画面タイプ、スクリーンショットの明瞭さ、構造の複雑さによって変わります。エンドツーエンドのレイテンシは、解像度、テキスト密度、キュー状況の影響を受けます。可用性は現在のサービス状態と適用契約に準拠します。

バウンディングボックスはピクセル精度であり、人間がアノテーションしたグラウンドトゥルースに対するボックス IoU（Intersection over Union）は、視覚的に明確な要素で平均 0.9 以上です。タイトなレイアウト内のネストされたテキスト — 6列のデータテーブルなど — が最も偏差が大きくなる部分であり、各要素の detectionScore が活きる場面です：ダウンストリームで使用する前に低信頼度ノードのロングテールをフィルタリングしてください。

出力フォーマット

デフォルトのレスポンスは JSON です。同じエンドポイントファミリーで2つの代替フォーマットが利用可能です：

• SVG — 検出されたシーンのベクター再レンダリング。特定のデザインツールに依存しない、ロスレスで編集可能なスクリーンショットのバージョンが必要な場合に便利です。
• Figma 互換ノード — Figma の REST API またはプラグイン API 経由で直接 Figma ファイルにドロップできる形状のツリー。これは Codia Figma プラグインが使用するフォーマットです。

JSON バージョンが最も柔軟です。SVG と Figma 出力は、同じ基盤スキーマを後処理するコンビニエンスラッパーです。

構築できる5つのもの

1. スクリーンショット → Figma パイプライン。 おそらく見たことがあるでしょう：画像をプラグインにドロップすると、完全に編集可能な Figma ファイルが得られます。プラグインは API 上の薄いクライアントです。独自のツール内でデザインの取り込みを行う場合は、プラグインをスキップして API を直接呼び出してください。

2. 大規模なビジュアル QA。 CI ランの間でスクリーンショットをピクセル差分する代わりに、要素ツリーを差分します。要素レベルの差分はサブピクセルのレンダリング差異、フォントフォールバック、アンチエイリアシングノイズを無視し、人間が実際に読める差分を生成します：「ボタン 'Continue' が右に 12px 移動し、4px の border-radius が追加された」。

3. AI 検索用のセマンティックインデックス。 UI 版 Pinterest のようなプロダクトを構築している場合 — あるいはデザインチームが「スパークライン付きのダークモードダッシュボード」を grep できるようにしたい場合 — スキーマがクエリ可能な構造を提供します。生の画像ではなく、要素タイプ、カラー、テキスト内容をインデックスしてください。

4. 画像のアクセシビリティリント。 スクリーンショットはアクセシブルではありませんが、型付き要素のツリーはアクセシブルにできます。JSON を a11y チェッカーに通すことで、チケット内の PNG として存在するデザインから、欠落した alt テキスト、低コントラストの組み合わせ、ラベルのないボタンを検出できます。

5. スクリーンショットからのコード生成。 スキーマは PDF やデザインパイプラインとセマンティクスを共有しているため、Codia のコードジェネレーターに直接パイプして React、Vue、Flutter、HTML/Tailwind を生成できます。画像を記述するのと同じツリーが UI を生成します。

エッジケースの処理

インテグレーションからの実践的な注意点：

• 非常に長いスクリーンショット（マーケティングサイトの全ページキャプチャなど）は、自然なセクション境界で分割するのが最善です。モデルは 10,000 ピクセル以上の高さの画像でも動作しますが、チャンクすることでより安定したグルーピングが得られます。
• ダークモード UI は十分にサポートされています — 検出器は背景の仮定に依存しません — ただし、ライトモードデザインのダークテーマレンダリングの場合、抽出されるカラーは画面上に表示されているものであり、背後のトークン値ではないことに注意してください。
• 手描きやスケッチ精度のモックアップ は動作しますが、スケッチが精密になるまで elementType の分布は汎用的な container と text ノードに偏ります。
• 複数のネストされたスクロール領域（ページ内でスクロールするサイドパネルなど）は単一のツリーにフラット化されます。モデルにはスクロールの概念がないため、独自にモデル化してください。

はじめ方

1. codia.ai/dashboard/developer でキーを取得してください。
2. 画像を送信（URL または base64）。1440×900 のデスクトップスクリーンショットがスイートスポットです。
3. ツリーを走査してください。信頼度閾値以上の要素のみが必要な場合は、processingMeta.detectionScore > 0.6 でプリフィルタリングしてノイズを除去してください。
4. 完全なリファレンス — スキーマ定義、レート制限、エラーコード — は /api にあります。

エンタープライズワークロードとして検討されている場合 — オンプレミス、プライベートリージョン、プロダクト固有のカスタム要素タイプなど — [email protected] が適切な窓口です。モデルは同じで、パッケージングが変わります。

UI はこれからも画像としてキャプチャされ続けます — バグレポート、Slack スレッド、Dribbble のショット、競合調査。これらの画像をクエリ可能な構造として扱えば、これまで手作業で行っていた大量の作業を解放できます。