PDF to Visual Struct

概要

PDF to Visual Struct は PDF ページを Codia の Visual Element Schema に変換します：バウンディングボックス、レイアウト設定、スタイル仕様を持つ型付き UI 要素の階層的な JSON ツリーです。このスキーマは Codia Studio と同じフォーマットであるため、ダウンストリームのコンシューマー — Figma インポーター、コードジェネレーター、ビジュアル QA パイプライン — は単一の安定したデータ形状に対して動作できます。

エンドポイント

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

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

リクエスト

リクエストは multipart/form-data です。

フィールド	型	必須	説明
`pdf_file`	file	はい	変換する PDF ファイル。リクエストごとに1ファイルです。
`page_no`	string	はい	変換するゼロインデックスのページ番号。複数ページの変換はクライアント側でループしてください。

例

bash

curl 'https://api.codia.ai/v1/open/pdf_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --form 'pdf_file=@"xx.pdf"' \
  --form 'page_no="0"'

レスポンス

json

{
  "configuration": {
    "scalingFactor": 1,
    "baseWidth": 1940,
    "measurementUnit": "px"
  },
  "pages": [
    {
      "visualElement": { /* ルート要素 */ }
    }
  ],
  "size": {
    "height": 1080,
    "width": 1940
  }
}

トップレベルフィールド

フィールド	説明
`configuration.baseWidth`	レイアウト解決時に使用される基準幅。異なるビューポート幅でレンダリングする場合、これに対してバウンディングボックスをスケーリングしてください。
`configuration.measurementUnit`	座標の単位 — 通常 `px`。
`configuration.scalingFactor`	事前適用されたスケーリングファクター。通常 `1`。
`size.width`、`size.height`	基準座標系での解決済みページキャンバス。
`pages[].visualElement`	ページツリーのルート要素。`childElements` を再帰的に走査してください。

Visual Element Schema

ツリーの各ノードは同じ形状を持ちます：

json

{
  "elementId": "pdf_page_1",
  "elementName": "PDF Document Page",
  "elementType": "Panel",
  "displayName": "First Page",
  "displayOrder": 0,
  "boundingBox": [0, 0, 595, 842],
  "layoutConfig": {
    "positionMode": "Normal",
    "flexibleMode": "Absolute"
  },
  "styleConfig": {
    "widthSpec":  { "sizing": "FIXED", "value": 595 },
    "heightSpec": { "sizing": "FIXED", "value": 842 },
    "backgroundSpec": {
      "type": "COLOR",
      "backgroundColor": { "rgbValues": [255, 255, 255] }
    }
  },
  "processingMeta": {
    "surfaceArea": 501490,
    "detectionScore": 0.92,
    "textContainerized": false
  },
  "childElements": []
}

フィールドリファレンス

フィールド	説明
`elementId`	このレスポンス内での安定した識別子。ページ間でグローバルに一意ではありません。
`elementType`	型付き要素クラス：`Panel`、`Text`、`Image`、`Icon`、`Button`、`Table`、`Chart` など50種以上。
`boundingBox`	基準座標での `[x, y, width, height]`。
`layoutConfig.positionMode`	`Normal`（フロー）または `Absolute`。
`layoutConfig.flexibleMode`	`Row`、`Column`、または `Absolute` — Figma のオートレイアウトセマンティクスに対応。
`styleConfig.widthSpec.sizing`	`FIXED`、`FILL_CONTAINER`、または `HUG_CONTENT`。
`styleConfig.backgroundSpec`	背景ペイント — カラー、グラデーション、または画像。
`processingMeta.detectionScore`	検出器の信頼度、`0.0` 〜 `1.0`。ダウンストリームで使用する前に低信頼度ノードをフィルタリングしてください。
`childElements`	子 Visual Element の配列。深さ優先走査で完全な階層が取得できます。

制限

設定	デフォルト
最大ファイルサイズ	50 MB
ドキュメントあたり最大ページ数	100
1分あたりの最大リクエスト数	プラン依存 — 料金ページをご覧ください。
ページあたりの一般的なレイテンシ	600 ms 〜 2 s

対応入力

テキストネイティブ PDF（デザインツール、オフィススイート、プログラムで生成されたもの）— 最高の忠実度。
スキャン PDF — OCR が自動的に適用されます。低解像度スキャンではより多くのノイズが発生します。
パスワード保護された PDF はサポートされていません。アップロード前にロック解除してください。

一般的なパターン

複数ページの変換

page_no を 0 からドキュメントの長さまでループし、プランの並行性制限まで並列実行します：

const pages = await Promise.all(
  pageNumbers.map((n) => fetch(ENDPOINT, buildRequest(file, n))),
)

低信頼度ノードのフィルタリング

function prune(node, minScore = 0.6) {
  node.childElements = (node.childElements || [])
    .filter((c) => c.processingMeta.detectionScore >= minScore)
    .map((c) => prune(c, minScore))
  return node
}

Figma へのラウンドトリップ

layoutConfig が Figma のオートレイアウトを反映しているため、ツリーをオートレイアウトフレームとして直接インポートできます。インポーターを自作したくない場合は PDF to Design Figma プラグインをご使用ください。

FAQ

1回の呼び出しで全ページを変換できますか？

1回の呼び出しではできません — エンドポイントはページ単位です。クライアント側でループして並列化してください。

変換の精度はどの程度ですか？

実際の認識品質は、PDF の生成元、テキストの明瞭さ、構造の複雑さによって変わります。スキャンされた法的フォームや手書き注釈の入力では低くなるため、常に processingMeta.detectionScore を確認してください。

フォントは保持されますか？

フォント名、サイズ、ウェイト、カラーは styleConfig に保持されます。保持されたフォントのレンダリングには、出力を使用する環境にフォントがインストールされている必要があります。

SDK はありますか？

SDK は不要です — API はプレーンな HTTP + JSON です。公式 SDK はロードマップにあります。

オンプレミスにデプロイできますか？

はい、エンタープライズプランで可能です。[email protected] までご連絡ください。

次のステップ

Visual Struct — 同じスキーマ、画像入力。
Remove BG — レンダリング出力への合成用の透過背景画像。
完全なエンドポイントリファレンスは /api#convert-pdf-to-design にあります。