> ## Documentation Index > Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt > Use this file to discover all available pages before exploring further. # preview_creative > preview_creative は、既存のクリエイティブマニフェストを単一またはバッチモードで閲覧可能な出力へレンダリングし、URL、画像、または HTML の出力を返します。 `preview_creative` は、既存のクリエイティブマニフェストを閲覧可能な出力へレンダリングします。入力マニフェストを生成または変更することはありません——それには [`build_creative`](/docs/creative/task-reference/build_creative) を使います。単一クリエイティブのプレビューとバッチプレビュー（複数クリエイティブで 5〜10 倍高速）の両方をサポートします。 **リクエストスキーマ**: [`/schemas/v3/creative/preview-creative-request.json`](https://adcontextprotocol.org/schemas/v3/creative/preview-creative-request.json) **レスポンススキーマ**: [`/schemas/v3/creative/preview-creative-response.json`](https://adcontextprotocol.org/schemas/v3/creative/preview-creative-response.json) ## クイックスタート ### 単一クリエイティブのプレビュー ```json theme={null} { "request_type": "single", "creative_manifest": { /* includes format_id, assets */ } } ``` レスポンス: ```json theme={null} { "response_type": "single", "previews": [ { "preview_id": "prev_001", "renders": [ { "render_id": "render_1", "output_format": "url", "preview_url": "https://creative-agent.example.com/preview/abc123", "role": "primary" } ], "input": { "name": "Default", "macros": {} } } ], "expires_at": "2027-02-15T18:00:00Z" } ``` プライマリレンダーを iframe に埋め込みます: ```html theme={null} ``` ### 直接の HTML 埋め込み iframe のオーバーヘッドなしのより高速なレンダリングのために、HTML を直接リクエストします: ```json theme={null} { "request_type": "single", "creative_manifest": { /* includes format_id, assets */ }, "output_format": "html" } ``` レスポンスには生の HTML が含まれます: ```json theme={null} { "response_type": "single", "previews": [ { "preview_id": "prev_002", "renders": [ { "render_id": "render_1", "output_format": "html", "preview_html": "
...
", "role": "primary" } ], "input": { "name": "Default", "macros": {} } } ], "expires_at": "2027-02-15T18:00:00Z" } ``` `output_format: "html"` は信頼できるクリエイティブエージェントとのみ使ってください。直接の HTML 埋め込みは iframe のサンドボックスをバイパスします。 ### バッチプレビュー（複数クリエイティブ） 1 回の API 呼び出しで複数のクリエイティブをプレビューします（5〜10 倍高速）: ```json theme={null} { "request_type": "batch", "requests": [ { "creative_manifest": { /* creative 1 */ } }, { "creative_manifest": { /* creative 2 */ } } ] } ``` レスポンスには結果が順序どおりに含まれます: ```json theme={null} { "response_type": "batch", "results": [ { "success": true, "creative_id": "creative_1", "response": { "previews": [...], "expires_at": "..." } }, { "success": true, "creative_id": "creative_2", "response": { "previews": [...], "expires_at": "..." } } ] } ``` ### バリアントプレビュー（配信後） 特定のバリアントが配信されたときにどう見えたかをプレビューします。`get_creative_delivery` レスポンスの `variant_id` を使います: ```json theme={null} { "request_type": "variant", "variant_id": "gen_mobile_morning" } ``` レスポンス: ```json theme={null} { "response_type": "variant", "variant_id": "gen_mobile_morning", "previews": [ { "preview_id": "prev_gen_morning", "renders": [ { "render_id": "render_1", "output_format": "url", "preview_url": "https://creative-agent.example.com/preview/variant/gen_mobile_morning", "role": "primary", "dimensions": { "width": 300, "height": 250 } } ] } ], "manifest": { "format_id": { "agent_url": "https://creative.example.com", "id": "display_300x250_generative" }, "assets": { "hero_image": { "asset_type": "image", "url": "https://cdn.creative.example.com/generated/mobile_morning_v1.jpg", "width": 300, "height": 250 }, "headline": { "asset_type": "text", "content": "Start Your Summer Right" } } }, "expires_at": "2027-02-15T18:00:00Z" } ``` `get_creative_delivery` の各バリアントは完全な `manifest` を含むため、それを再レンダリングするために、そのマニフェストを標準の単一リクエストとして直接 `preview_creative` に渡すこともできます。 ## リクエストパラメータ すべてのモードは、`request_type` を判別子とする単一のフラットなオブジェクトを使います。 | パラメータ | 型 | 必須 | 説明 | | ------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `request_type` | string | Yes | `"single"`、`"batch"`、または `"variant"` | | `creative_manifest` | object | Single | フォーマットに必要なすべてのアセットを持つ完全なクリエイティブマニフェスト。 | | `format_id` | FormatID | No | フォーマット識別子（agent\_url + id）。省略した場合は `creative_manifest.format_id` にデフォルト。単一モードで使用。 | | `inputs` | array | No | 複数のプレビューバリアント向けの入力セットの配列。単一モードで使用。 | | `quality` | string | No | `"draft"`（高速、低忠実度）または `"production"`（フル品質）。バッチモードでは、すべてのリクエストのデフォルトを設定。 | | `output_format` | string | No | `"url"`（デフォルト）または `"html"`。バッチモードでは、すべてのリクエストのデフォルトを設定。 | | `item_limit` | integer | No | プレビューバリアントごとにレンダリングするカタログアイテムの最大数。単一モードで使用。 | | `template_id` | string | No | カスタムフォーマットのレンダリング用の特定のテンプレート ID。単一モードで使用。 | | `requests` | array | Batch | 1〜50 のプレビューリクエストの配列。各項目は `creative_manifest`（必須）、`format_id`、`inputs`、`quality`、`output_format`、`item_limit`、`template_id` を受け入れる。 | | `variant_id` | string | Variant | `get_creative_delivery` からのプラットフォーム割り当てのバリアント識別子。 | | `creative_id` | string | No | コンテキスト用のクリエイティブ識別子。バリアントモードで使用。 | **必須**列の値: *Single* = `request_type` が `"single"` のときに必須、*Batch* = `"batch"` のとき必須、*Variant* = `"variant"` のとき必須。 ### 入力セット 異なるコンテキストを提供することで、複数のプレビューバリアントを生成します: ```json theme={null} { "inputs": [ { "name": "Desktop", "macros": { "DEVICE_TYPE": "desktop" } }, { "name": "Mobile", "macros": { "DEVICE_TYPE": "mobile" } }, { "name": "Morning Context", "context_description": "User commuting to work" } ] } ``` **利用可能なマクロ**: `DEVICE_TYPE`、`COUNTRY`、`CITY`、`DMA`、`GDPR`、`US_PRIVACY`、`CONTENT_GENRE` など。 **コンテキスト記述**: ホストリードの音声広告のような AI 生成コンテンツ向け。 ## レスポンスフォーマット ### 単一モードのレスポンス ```typescript theme={null} { response_type: "single"; previews: Preview[]; // One per input (or one default) interactive_url?: string; // Optional sandbox for interactive formats expires_at?: string; // Optional ISO 8601 expiration; omitted means no expiration } ``` ### バッチモードのレスポンス ```typescript theme={null} { response_type: "batch"; results: Array<{ success: boolean; creative_id: string; response?: { previews: Preview[]; expires_at?: string; }; errors?: Array<{ code: string; message: string; }>; }>; } ``` ### プレビューの構造 ```typescript theme={null} { preview_id: string; renders: Array<{ render_id: string; output_format: "url" | "html" | "both"; preview_url?: string; // When output_format is "url" or "both" preview_html?: string; // When output_format is "html" or "both" role: string; // "primary", "companion", etc. dimensions?: { width: number; height: number; }; }>; input: { name: string; macros?: Record; context_description?: string; }; } ``` **マルチレンダーフォーマット**: 一部のフォーマットは複数のピース（動画 + コンパニオンバナー）を生成します。それぞれが独自の `render_id` と `role` を持ちます。 ## 生成系クリエイティブのプレビュー 生成系フォーマット——コンテキストディスプレイ、AI 生成ネイティブ、会話型広告——では、クリエイティブは配信時まで存在しません。プレビューは二つの異なる目的を果たします: ### フライト前: 代表的なサンプル キャンペーンが実行される前に、単一またはバッチモードを使って、異なるコンテキストが与えられたときにエージェントが*何を生成しうるか*をプレビューします。配信時の条件をシミュレートするために `context_description` を持つ `inputs` を渡します: ```json theme={null} { "$schema": "/schemas/creative/preview-creative-request.json", "request_type": "single", "quality": "draft", "creative_manifest": { "format_id": { "agent_url": "https://ads.seller-example.com", "id": "contextual_display_generative" }, "assets": { "brief": { "asset_type": "brief", "name": "Sustainability story", "objective": "awareness", "messaging": { "key_messages": ["Highlight our sustainability story. Match tone to editorial context."] } } } }, "inputs": [ { "name": "Tech article", "context_description": "Article about semiconductor manufacturing" }, { "name": "Lifestyle blog", "context_description": "Blog post about sustainable living" } ] } ``` これらのプレビューは*代表的*であって決定的ではありません。実際の配信時の出力は、完全にはシミュレートできないライブシグナル（実際のページコンテンツ、ユーザーデバイス、時刻）に依存します。ブリーフとクリエイティブの方向性を高速に反復するにはドラフト品質を使い、ステークホルダーのレビューにはプロダクション品質を使います。 ### フライト後: 正確なリプレイ キャンペーンが実行された後、バリアントモードを使って、正確に何が配信されたかを確認します。`get_creative_delivery` からの `variant_id` を渡します: ```json theme={null} { "request_type": "variant", "variant_id": "gen_tech_mobile_001" } ``` レスポンスには、バリアントの実際のマニフェスト——エージェントがそのコンテキスト向けに生成した特定の見出し、画像、レイアウト——が含まれます。これは再生成ではなく、忠実なリプレイです。 ### 期待値の設定 | 側面 | 標準クリエイティブ | 生成系クリエイティブ | | ----------------------- | ----------------------- | --------------------------------------- | | フライト前プレビュー | 正確——見えるものが実行される | 代表的——シミュレートされた条件下でのブリーフに対するエージェントの解釈を示す | | フライト後プレビュー | フライト前と同じ | 正確——バリアントモードを介した配信済み出力の忠実なリプレイ | | `quality: "draft"` | 高速なワイヤーフレーム品質のレンダー | クリエイティブの方向性をレビューするための高速で低忠実度の生成 | | `quality: "production"` | フル忠実度のレンダー | ステークホルダーの承認のためのフル品質の生成 | | バリアントの数 | 通常 1（またはいくつかのデバイスバリアント） | 潜在的に数千——コンテキストごとに 1 つ | すべてのインプレッションが異なるクリエイティブを生成する生成系フォーマット（AI チャットやリアルタイムコンテキストのような）では、フライト前プレビューは*広告*そのものではなく*分布からのサンプル*として理解するのが最善です。ブリーフとブランドアイデンティティが分布を制約し、プレビューはエージェントがそれらの制約を正しく解釈することを検証できるようにします。 ### 会話型とインタラクティブなフォーマット 広告がステートフルなフォーマット——AI チャット、インタラクティブな体験、会話型ネイティブ——では、プレビューは追加の意味を帯びます: * **フライト前**は、代表的な最初のインタラクションまたはシミュレートされた会話をレンダリングします。プレビューレスポンスの `interactive_url` フィールド（存在する場合）は、レビュアーが体験と直接やり取りできるサンドボックスを提供します。異なる会話のエントリーポイントをシミュレートするには `context_description` を使います。 * **フライト後**のバリアントリプレイは、実際に起きたやり取りを示します。マルチターンフォーマットでは、バリアントマニフェストがエージェントが生成した完全なコンテンツ（メッセージシーケンス、レスポンス、表示されたメディアアセット）を捕捉します。詳細のレベルはエージェントに依存します——完全なトランスクリプトを提供するものもあれば、匿名化されたユーザーシグナルで要約されたコンテンツを提供するものもあります。 これらのフォーマットは、フライト前とフライト後の間のギャップが最も大きいです: フライト前プレビューは一つの可能な会話パスを近似できるだけですが、ライブ体験は各ユーザーに適応します。トーン、ガードレール、ブランドの一貫性を検証するのに十分なシナリオをプレビューしてください。 ### 品質の不一致 要求された品質レベルがサポートされていない場合、エージェントは提供できる最善の品質でレンダリングします。プロトコルはエージェントに両方のレベルのサポートを要求しません——1 つの忠実度でしか生成しないエージェントはパラメータを無視します。実際に使われた品質をエコーバックするレスポンスフィールドはないため、ワークフローで品質の正確さが重要な場合は、目視で検証するか、`list_creative_formats` を通じてエージェントの機能について尋ねてください。 ### プレビューの有効期限とバリアントの保持 プレビューレスポンスには `expires_at` タイムスタンプが含まれる場合があります。存在する場合、コンシューマはその時刻を過ぎたプレビュー URL を無効として扱い、再利用の前に再生成すべきです。`expires_at` が省略された場合、プレビュー URL は期限切れになりません。生成系クリエイティブでは、フライト前プレビューを再生成すると異なる出力が生成される可能性があります——同じブリーフとコンテキストでも、毎回異なるクリエイティブになりえます。 ### プレビュー URL の耐久性 `preview_url` は、バイヤーと MCPUI ホストがレンダリングするプロトコルリソースです。AdCP は 3.x でプレビューレンダー用の別個の耐久性のあるアセットポインタを定義しません。クリエイティブエージェントが内部のアセットキー、リソース URI、またはストレージオブジェクト ID を必要とする場合、スキーマが将来のフィールドを追加しない限り、それはエージェント内部に留まります。 クリエイティブエージェントは、各 `preview_url` をレスポンスの `expires_at` タイムスタンプまで参照解決可能に保たなければなりません（MUST）。`expires_at` が省略された場合、URL はプロトコルレベルの有効期限を持たず、エージェントが帯域外で明示的に失効またはパージするまで参照解決可能でなければなりません。マルチプロセスまたはマルチポッドのデプロイでは、プレビュー URL をポッドローカルの `Map`/LRU の状態だけで裏付けないでください。ブラウザのフェッチ、後のリファインメント呼び出し、またはレビュアーのセッションが、プレビューを作成したのとは異なるプロセスに着地する可能性があるためです。 耐久性のあるストレージは、恒久的な公開 CDN ホスティングを必要としません。ルートが共有ストレージ（データベース行、オブジェクトストアのキー、共有キャッシュ層など）から、表明されたライフタイムにわたってレンダーを回復できる限り、プレビュー URL はクリエイティブエージェントの認証済みプレビュールートを通じて解決できます。 バリアントプレビュー（フライト後）は、エージェントがバリアントデータを保持することに依存します。エージェントはバリアントデータを無期限に保持する必要はありません。エージェントがパージしたバリアントのバリアントプレビューをリクエストした場合、標準のエラーレスポンスを期待してください。長期間実行されるキャンペーンでは、バリアントプレビューが利用可能なままだと仮定するのではなく、定期的に取得してアーカイブしてください。 ## 例 ### デバイスバリアント ```json theme={null} { "$schema": "/schemas/creative/preview-creative-request.json", "request_type": "single", "creative_manifest": { "format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "native_responsive" }, "assets": { "hero_image": { "asset_type": "image", "url": "https://cdn.example.com/hero.jpg", "width": 1200, "height": 627 }, "headline": { "asset_type": "text", "content": "Veterinarian Recommended" } } }, "inputs": [ { "name": "Desktop", "macros": { "DEVICE_TYPE": "desktop" } }, { "name": "Mobile", "macros": { "DEVICE_TYPE": "mobile" } } ] } ``` ### HTML 出力を伴うバッチ グリッドレイアウト用に複数のクリエイティブをプレビューします: ```json theme={null} { "request_type": "batch", "output_format": "html", "requests": [ { "creative_manifest": { /* creative 1 */ } }, { "creative_manifest": { /* creative 2 */ } } ] } ``` ### AI 生成音声のプレビュー ```json theme={null} { "$schema": "/schemas/creative/preview-creative-request.json", "request_type": "single", "creative_manifest": { "format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "audio_host_read_30s" }, "assets": { "script_template": { "content": "This episode brought to you by {{BRAND_NAME}}..." }, "brand_voice": { "content": "Friendly, enthusiastic, conversational." } } }, "inputs": [ { "name": "Weather Podcast", "context_description": "Podcast discussing weather patterns" }, { "name": "Fitness Podcast", "context_description": "Podcast about marathon training" } ] } ``` ## HTTP ステータスコード **単一モード:** * **200 OK** - プレビューが正常に生成された * **400 Bad Request** - 無効なマニフェストまたは format\_id * **404 Not Found** - フォーマットがサポートされていない **バッチモード:** * **200 OK** - バッチが処理された（個々の `success` フィールドを確認） * **400 Bad Request** - 無効なバッチ構造 ## 主なポイント * すべてのレンダーの `preview_url` は、iframe 埋め込み用の HTML ページを返す * 10 件以上のプレビューのグリッドには `output_format: "html"` を使う（iframe のオーバーヘッドなし） * バッチモードは個別リクエストより 5〜10 倍高速 * プレビュー URL は `expires_at` が存在するときにのみ期限切れになる。`expires_at` の省略はプロトコルレベルの有効期限がないことを意味する * プレビュー URL を、URL の表明されたライフタイムを生き延びるストレージで裏付ける。プロセスローカルのマップは、単一プロセスのデモやプロセスライフタイムより短い URL にのみ適切 * 各結果の `success` フィールドを確認して部分的なバッチ失敗を扱う ## 関連ドキュメント * [高度なプレビューパターン](/docs/creative/task-reference/preview_creative-advanced) - キャッシュ、ワークフロー、実装ノート * [クリエイティブマニフェスト](/docs/creative/creative-manifests) - マニフェストの構造