> ## 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.
# build_creative
> build_creative は AdCP において、自然言語のブリーフからプロダクション対応のアセットまで、広告クリエイティブマニフェストを生成・変換・取得します。
特定のフォーマット向けのクリエイティブマニフェストを変換・生成・取得します。結果のマニフェストの視覚的なプレビューをレンダリングするには、それを [`preview_creative`](/docs/creative/task-reference/preview_creative) に渡します。3 つのモードをサポートします。
1. **生成（Generation）**: ブリーフまたはシードアセットからマニフェストを作成する（`message` + `creative_manifest`）
2. **変換（Transformation）**: 既存のマニフェストを別のフォーマットに適応させる（`creative_manifest` + `target_format_id`）
3. **ライブラリ取得（Library retrieval）**: エージェントのライブラリから `creative_id` を解決し、広告配信アセット付きのマニフェストを生成します
生成および変換では、`build_creative` はクリエイティブマニフェストを入力として受け取り、クリエイティブマニフェストを出力します。ライブラリ取得では、[`list_creatives`](/docs/creative/task-reference/list_creatives) で取得した `creative_id` を指定すると、エージェントがライブラリから解決します。
フォーマット ID とフォーマットの参照方法については、[クリエイティブフォーマット - フォーマットの参照](/docs/creative/formats#referencing-formats)を参照。
## リクエストパラメーター
| パラメーター | 型 | 必須 | 説明 |
| ------------------------------ | ------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message` | string | No | クリエイティブエージェントへの自然言語の指示。生成時はクリエイティブ方向性を提供します。変換時はクリエイティブの適応方法をガイドします。リファインメント時は変更内容を記述します。 |
| `creative_manifest` | object | No | 変換または生成の元となるクリエイティブマニフェスト（[Creative Manifest](https://adcontextprotocol.org/schemas/v3/core/creative-manifest.json) を参照）。純粋な生成では、ターゲットの format\_id と必要な入力アセットを含めます。変換では適応させる完全なクリエイティブを指定します。`creative_id` が指定された場合、エージェントはライブラリからクリエイティブを解決し、このフィールドは無視されます。 |
| `creative_id` | string | No | エージェントのライブラリ内のクリエイティブへの参照。クリエイティブエージェントはこれをライブラリのマニフェストに解決します。タグ生成やフォーマット変換で既存のクリエイティブを取得する場合、`creative_manifest` の代わりに使用します。 |
| `concept_id` | string | No | クリエイティブを含むクリエイティブコンセプト。同じ `creative_id` が複数のコンセプトに存在する場合に曖昧さを解消するために使用します。 |
| `media_buy_id` | string | No | タグ生成コンテキスト用のバイヤーのメディアバイ参照。クリエイティブエージェントが広告サーバーも兼ねる場合（CM360 など）、プレースメント固有のタグを生成するために必要なトラフィッキングコンテキストを提供します。プラットフォームがクリエイティブレベルでタグを生成する場合（Flashtalking、Celtra など）は省略します。これはバイヤーの参照であり、`create_media_buy` から得られるセラーが割り当てた識別子です。 |
| `package_id` | string | No | メディアバイ内のバイヤーのパッケージまたはラインアイテム参照。クリエイティブエージェントがラインアイテムレベルのコンテキストを必要とする場合に `media_buy_id` とともに使用します。特定のパッケージにスコープされないタグを取得する場合は省略する（広告サーバーは同じタグを返す場合があります）。 |
| `target_format_id` | object | Conditional | 生成する単一のフォーマット ID。`agent_url` と `id` フィールドを持つオブジェクト。3.1 の正準的なクリエイティブエージェントルーティングでは、`id` は表明された `creative.supported_formats[].capability_id` です。レガシーの名前付きフォーマット ID は移行期間中は引き続き受け入れられます。`target_format_ids` と相互に排他的であり、どちらか一方のみを指定すること。 |
| `target_format_ids` | array | Conditional | 1 回の呼び出しで生成するフォーマット ID の配列。各要素は `agent_url` と `id` フィールドを持つオブジェクト。3.1 の正準的なクリエイティブエージェントルーティングでは、各 `id` は表明された `creative.supported_formats[].capability_id` です。レガシーの名前付きフォーマット ID は移行期間中は引き続き受け入れられます。`target_format_id` と相互に排他的であり、どちらか一方のみを指定すること。フォーマットごとに 1 つのマニフェストを返します。 |
| `brand` | object | No | `domain` フィールドを持つブランド参照。`/.well-known/brand.json` 経由でブランドアイデンティティを解決します。ブランドレベルのコンテキスト（カラー、ロゴ、トーン）を提供します。 |
| `quality` | string | No | 品質ティア: `"draft"`（反復のための高速・低忠実度）または `"production"`（最終納品のためのフル品質）。省略した場合、クリエイティブエージェントが独自のデフォルトを使用します。 |
| `item_limit` | integer | No | **1 つのクリエイティブ内**で使用するカタログアイテムの最大数。カタログ駆動フォーマットの生成コストを抑制します（例: 1,000 プロダクトのカタログから作る 6 枚カードのカルーセル）。アイテムをまたいでファンアウトする `max_creatives` とは異なります。 |
| `transformer_id` | string | No | ビルドを実行するトランスフォーマーを 1 つ選択します（[`list_transformers`](/docs/creative/task-reference/list_transformers) で発見）。要求するターゲットフォーマットは、そのトランスフォーマーの `output_format_ids` の部分集合でなければなりません（MUST）。トランスフォーマーの `per_unit` レートがそのビルドの価格の源です。 |
| `config` | object | No | 選択したトランスフォーマーの `params[].field` にキー付けされた型付き設定バッグ（例: `{ "voice": "isaac", "speaking_rate": 1.1 }`）。クリエイティブエージェントは、未知のキーと範囲外の値を、フィールドを特定したエラーで拒否しなければなりません（MUST、厳格なバリデーション）——宣言された params ではないベンダー固有のつまみは `ext` に入れます。`transformer_id` を伴う場合にのみ意味を持ちます。 |
| `max_creatives` | integer | No | カタログのファンアウト軸: 最大 N 個の**別個のクリエイティブを、カタログアイテムごとに 1 つ**生成します（サンプル——例: 150 のうち 5）。単一のクリエイティブ*内*で使うアイテムを制限する `item_limit` とは異なります。`refine_from_build_variant_id` と相互排他的。`BuildCreativeVariantSuccess` のレスポンス形をトリガーします。エージェントが `creative.multiplicity.supports_catalog_fanout` を表明する場合にのみサポートされます。`max_creatives_limit` を超える値は拒否ではなく**クランプ**されます（不足は `items_returned` \< `items_total` で示されます）。 |
| `signal_conditions` | array | No | シグナルのファンアウト軸: **シグナル条件ごとに** 1 つの別個のクリエイティブを生成し、それぞれが独自のターゲティングで保持・トラフィックされます（雨のクリエイティブ AND 晴れのクリエイティブ）。各項目は [SignalTargeting](/docs/signals/specification) です。`max_creatives` の兄弟であり、それと合成されます（カタログ × 条件）。このレイヤーでは助言的です（[#5280](https://github.com/adcontextprotocol/adcp/issues/5280)）——トラフィッキング互換性はセールス側で `SIGNAL_TARGETING_INCOMPATIBLE` により強制されます。エージェントが `creative.multiplicity.supports_signal_fanout` を表明する場合にのみサポートされます。`max_signal_conditions_limit` を超えるカウントは**クランプ**されます。[シグナルのファンアウト](#バリアントレスポンス)を参照。 |
| `selection_strategy` | string | No | `max_creatives` \< 適格アイテム数のときにエージェントがどうサンプリングするか: `audience_relevance`（ユーザー側、同じ `signal_ref` ポインタでランク付け）、`contextual_fit`（コンテンツ側、コンテキストシグナルで同じ仕組み）、`performance`（過去のデリバリー）、`proximity`、`inventory_priority`（セラー側）、または `random`（デフォルト）。順序は `rank`/`recommended` で表れます。サポートされる集合は `creative.multiplicity.selection_strategies[]`。 |
| `max_variants` | integer | No | **クリエイティブごとに**生成する代替レンダーの数（best-of-N）。デフォルト `1`。生成されたすべてのバリアントに対して課金され、1 つ以上を保持するのは別のトラフィッキングステップです。エージェントが `creative.multiplicity.supports_variants` を表明する場合にのみサポートされます。`max_variants_limit` を超える値はクランプされます。 |
| `variant_axis` | object | No | バリアントが異なる次元を記述します。`dimension`（`voice` \| `theme` \| `best_of_n` \| `transformer_config` \| `custom`）、任意の `values[]`（軸に沿って列挙する明示的な値）、任意の `field`（スイープする `config` param——`dimension` が `transformer_config` のとき必須）、任意の `label` を持つオブジェクト。 |
| `keep_mode` | string | No | 何個のバリアントを保持する意図かをエージェントに伝える助言的ヒント: `"keep_all"`、`"keep_one"`、または `"keep_some"`。デフォルト `"keep_all"`。助言のみ——生成されたすべてのバリアントに対して課金されます。レスポンスは `keep_mode_applied` をエコーするので、ヒントが受け取られた確認になります（課金紛争のための監査証跡）。 |
| `evaluator` | object | No | **実験的**（[ステータス](/docs/reference/experimental-status)、機能 id `creative.evaluator`）。エージェントの best-of-N に対して**ゲート後にランク付け**するパイプラインを駆動する助言的な評価器（[Evaluator Spec](https://adcontextprotocol.org/schemas/v3/core/evaluator-spec.json)）: 1 つのソース形式（`exemplars` / アカウントで手配された `evaluator_id` / `agent_url`）、任意のハードな `feature_requirement[]` **ゲート**（不合格は破棄——推奨リーフの内部的な刈り込みであり、すでに生成された課金対象リーフをブロックすることはない）、明示的な `rank_by` の順序（`[{feature_id, direction: maximize\|minimize}]`）、許可リストに載った `feature_agent` ポインタ。機能の発見は [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) の `governance.creative_features` を使い、評価器は同じ機能 ID を `variants[].eval.features[]` で返します。`evaluator_id` はそのカタログからは発見されず、事前プロビジョニングされたアカウントプリセットです。外部エージェント（`feature_agent.agent_url` / `agent_url`）はセラーの `creative_policy.accepted_verifiers[]` に含まれていなければなりません（MUST）——リスト外は `EVALUATOR_AGENT_NOT_ACCEPTED`。`creative.supports_evaluator` が必要で、なければ無視されます。リーフごとの `variants[].eval` ブロックを埋めます。[`variants[].eval`](#フィールド説明) と [評価器の認証](#評価器の認証)を参照。 |
| `refine_from_build_variant_id` | string | No | 以前に生成したバリアントをリファインします: その `build_variant_id` から、`message` の自然言語指示と任意の `config` デルタを適用して再ビルドし、**新しい**リネージ連結されたバリアントを返します（変更ではない）。`transformer_id` とターゲットフォーマットは親から継承されます。`max_variants`/`variant_axis` と合成されます。`max_creatives` とは相互排他的。`creative.supports_refinement` が必要——なければ `UNSUPPORTED_FEATURE`。未知の、または保持されなくなった参照は `REFERENCE_NOT_FOUND`（`error.field` = `refine_from_build_variant_id`）。[リファインメント](#リファインメント)を参照。 |
| `mode` | string | No | `"execute"`（デフォルト）は生成して課金します。`"estimate"` は**ドライラン**——何も生成せず課金もせず、このリクエストの入力に対して計算された `BuildCreativeEstimate` のコスト帯（`cost_low`/`cost_high`）を返します。`creative.supports_spend_controls` が必要。[支出コントロール](#支出コントロール)を参照。 |
| `max_spend` | object | No | 呼び出しごとのハードな支出上限 `{ amount, currency }`。エージェントは、次のリーフが `amount` を超えるまでリーフを生成し、その後停止して `budget_status: "capped"` の部分結果を返します。`creative.supports_spend_controls` が必要。1 回の呼び出しを上限とします——リファインメントループの制限はバイヤー側で行います。[支出コントロール](#支出コントロール)を参照。 |
| `include_preview` | boolean | No | true の場合、マニフェストと同時にプレビューレンダリングをリクエストします。これをサポートするエージェントはレスポンスに `preview` オブジェクトを返します。サポートしないエージェントは単純に省略します。 |
| `preview_inputs` | array | No | `include_preview` が true の場合のプレビュー生成用入力セット。各エントリに `name`（必須）、オプションの `macros`、オプションの `context_description` を持ちます。省略した場合、エージェントは単一のデフォルトプレビューを生成します。`target_format_id`（シングルフォーマット）でのみサポートされ、マルチフォーマットリクエストでは無視されます。 |
| `preview_quality` | string | No | インラインプレビューのレンダー品質: `"draft"` または `"production"`。ビルドの `quality` とは独立しています。ドラフトでビルドしてプロダクション品質でプレビューすることも、その逆も可能。`include_preview` が true の場合のみ使用されます。 |
| `preview_output_format` | string | No | プレビューレンダリングの出力フォーマット: `"url"`（デフォルト）または `"html"`。`include_preview` が true の場合のみ使用されます。 |
| `macro_values` | object | No | 出力マニフェストのアセットに事前置換するマクロ値。キーはユニバーサルマクロ名（例: `CLICK_URL`、`CACHEBUSTER`）で、値はリテラルの置換文字列。クリエイティブエージェントはユニバーサルマクロをプラットフォームのネイティブ構文に変換します。ここで指定されないマクロは、セールスエージェントが配信時に解決するための `{MACRO}` プレースホルダーとして残る。 |
| `account` | [AccountRef](/docs/building/by-layer/L2/accounts-and-agents#account-references) | No | 価格と請求のためのアカウント参照。存在する場合、クリエイティブエージェントはレートカードからアカウント固有の価格を適用し、ビルドをアカウントに対して記録し、クォータを強制できます。サービスに課金するクリエイティブエージェントでは必須です。 |
| `push_notification_config` | object | No | `build_creative` が `submitted` を返すときの、非同期の終端の完了/失敗通知のための操作スコープのウェブフック設定。submitted タスクは、このフィールドの有無に関わらず `get_task_status` でポーリング可能です。エージェントは、このフィールドが存在するというだけの理由で `submitted` を返してはなりません（MUST NOT）。 |
### 価格レスポンスフィールド
クリエイティブエージェントが課金し `account` が提供された場合、レスポンスには価格フィールドが含まれます:
| フィールド | 型 | 説明 |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `pricing_option_id` | string | どのレートカードの価格オプションが適用されたか |
| `vendor_cost` | number | このビルドで発生したコスト。コストが配信時に発生する CPM 価格のクリエイティブでは 0 の場合があります。 |
| `currency` | string | ISO 4217 通貨コード |
| `consumption` | object | 構造化された消費の詳細——`tokens`、`images_generated`、`renders`、`duration_seconds`。[`creative-consumption.json`](https://adcontextprotocol.org/schemas/v3/core/creative-consumption.json)を参照。コスト検証のための情報提供であり、`vendor_cost` が請求の信頼できる情報源です。 |
非同期ビルド（`context_id` ポーリングを伴う `status: "working"`）では、価格フィールドは最終的な完了レスポンスにのみ現れます。
### レシピのアイデンティティ
エージェントは、シングルフォーマットの成功レスポンスでトップレベルの `recipe_hash` を返してもよく（MAY）、多重度/リファインメントのリーフで `variants[].recipe_hash` を返してもよい（MAY）。マルチフォーマットの `creative_manifests[]` レスポンスは、このリビジョンでは `recipe_hash` を運びません。出力ごとのレシピアイデンティティが必要な場合はバリアント形（`max_variants`）を要求してください。この値は、ビルドを決定する入力に対する ETag スタイルのアイデンティティです: エージェントが計算し、不透明で、そのエージェントにスコープされます。バイヤーは同じエージェントからのレスポンス間でのみ比較できます。
`recipe_hash` は、出力バイトや法的/開示のエンベロープではなく、入力レシピを識別します。非決定的なビルドは、同じ `recipe_hash` で異なるピクセル、タグ、バリアントを返すことがあります。この値は「同じクリエイティブ」ではなく「同じ指示」を意味します。ファンアウトのレスポンスでは、同じレシピから生成された best-of-N リーフは同じ値を共有すべきです（SHOULD）。クライアントが共有ソースで代替をグループ化できるようにするためです。`recipe_hash` と `build_variant_id` の両方が現れる場合、`build_variant_id` が出力リーフとリネージを識別し、`recipe_hash` は入力レシピを識別します。どちらも他方を含意しません。ビルドからデリバリーへのパフォーマンスの結合には、依然として `recipe_hash` 単独ではなく、トラフィッキングを生き延びるリネージ識別子を使います。
**重要**: 必須の入力アセットは、個別のタスクパラメーターとしてではなく、`creative_manifest.assets` オブジェクトに含めること。フォーマット定義が必要なアセットを指定します。ダイナミッククリエイティブのカタログコンテキストは `creative_manifest.assets` マップ経由で提供すること。
### 評価器の認証
`build_creative.evaluator` は評価器を選択または校正します。評価器の呼び出しを認証するものではありません。評価器の API キー、ベアラートークン、クライアントシークレット、`Authorization` の値、JWK、JWKS ドキュメント、JWKS URI を、`evaluator`、`context`、`ext`、その他のペイロードフィールドに入れないでください。クレデンシャルまたは信頼素材のペイロードキーは非準拠であり、[`CREDENTIAL_IN_ARGS`](/docs/building/by-layer/L3/error-handling#authentication-and-access)で拒否されるべきです。
`evaluator.agent_url` または `evaluator.feature_agent.agent_url` が外部の評価器を指す場合、生成を行うクリエイティブエージェントは、通常の AdCP トランスポート認証チャネルを使って、その評価器の [`get_creative_features`](/docs/governance/creative/get_creative_features) エンドポイントを呼びます。評価器は、[RFC 9421 のリクエスト署名](/docs/building/by-layer/L1/security#request-signing)と JWKS ディスカバリー、mTLS、または事前プロビジョニングされた Bearer/API キークレデンシャルを介して、呼び出し元としてのクリエイティブ/セラーエージェントを認証します。`agent_url`、`account`、`context`、`ext` のようなペイロードフィールドはアイデンティティの主張ではなく、クレデンシャルとして扱ってはなりません。
許可リストのチェックが依然として最初に行われます: `creative_policy.accepted_verifiers[]` にない外部評価器の URL は、いかなるアウトバウンド呼び出しの前に `EVALUATOR_AGENT_NOT_ACCEPTED` で拒否されます。バイヤーは、メディアバイ/プロダクトのコンテキストが公開する場合はセラーの公開する `creative_policy.accepted_verifiers[]` から、スタンドアロンのクリエイティブエージェント統合ではアカウントのプロビジョニングから、受理される評価器の URL を知ります。URL がリストにあるが評価器に到達できない、またはクリエイティブエージェントのトランスポート認証を拒否する場合、ビルドはビルド全体を失敗させるのではなく、助言的な `errors[]` の注記とともにセラーデフォルトのランキングに劣化します。
### 生成コントロール
ジェネレーティブフォーマットでは、生成プロセスを制御する 2 つのオプションパラメーターがあります。
* **`quality`**: 生成の忠実度を制御します。高速反復（レイアウト・コピー・構成のレビュー）には `"draft"` を、最終レンダーには `"production"` を使用します。ドラフト出力では低解像度の画像、単純化されたエフェクト、またはプレースホルダー要素が使用される場合があります。気に入ったドラフトのプロダクション版を作成するには、そのドラフトの出力マニフェストを `creative_manifest` として `quality: "production"` と共に渡します。注意: `preview_creative` も `quality` を受け取るが、*レンダー*の忠実度を独立して制御します。[ジェネレーティブクリエイティブのプレビュー](/docs/creative/task-reference/preview_creative#previewing-generative-creative)を参照。
* **`item_limit`**: カタログ駆動フォーマットで、生成時に使用するカタログアイテム数を上限設定します。カタログに 1,000 商品あっても、必要なヒーロー画像は 4 枚だけかもしれない。クリエイティブエージェントは関連性またはカタログの順序に基づいて上位アイテムを選択します。`item_limit` がカタログ要件の `max_items`（フォーマットの catalog requirements から）を超える場合、クリエイティブエージェントは小さい方を使用すること。省略した場合、クリエイティブエージェントはカタログサイズとフォーマット要件に基づいて決定します。
## ユースケース
### 純粋な生成（スクラッチからの作成）
純粋な生成では、フォーマットで定義された必須入力アセットを含む最小限のソースマニフェストを提供します。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-request.json",
"idempotency_key": "a1b2c3d4-0000-4000-8000-000000000000",
"message": "Create a banner promoting our winter sale with a warm, inviting feel",
"target_format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250_generative"
},
"brand": {
"domain": "mybrand.com"
},
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250_generative"
},
"assets": {
"offering_catalog": {
"asset_type": "catalog",
"type": "offering",
"items": [
{
"offering_id": "winter-sale",
"name": "Winter Sale Collection",
"description": "50% off all winter items"
}
]
}
}
}
}
```
### 変換（既存クリエイティブの適応）
変換では、完全なソースマニフェストを提供します。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-request.json",
"idempotency_key": "a1b2c3d5-0000-4000-8000-000000000001",
"message": "Adapt this creative for mobile, making the text larger and CTA more prominent",
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250"
},
"assets": {
"banner_image": {
"asset_type": "image",
"url": "https://cdn.example.com/original-banner.png",
"width": 300,
"height": 250
},
"headline": {
"asset_type": "text",
"content": "Winter Sale - 50% Off"
}
}
},
"target_format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_mobile_320x50"
}
}
```
### フォーマットリサイズ
既存のクリエイティブを別のサイズに変換します。
```json theme={null}
{
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_728x90"
},
"assets": { /* complete assets */ }
},
"target_format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250"
}
}
```
### ライブラリ取得
エージェントのライブラリからクリエイティブを取得し、広告配信アセット付きのマニフェストに解決します。[`list_creatives`](/docs/creative/task-reference/list_creatives) で `creative_id` を把握していて、クリエイティブエージェントにタグ（HTML、JavaScript、VAST）付きの配信対応マニフェストを生成させたい場合に使用します。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-request.json",
"idempotency_key": "a1b2c3d6-0000-4000-8000-000000000002",
"creative_id": "ft_88201",
"concept_id": "concept_holiday_2026",
"target_format_id": {
"agent_url": "https://creative.example.com",
"id": "display_static",
"width": 300,
"height": 250
},
"macro_values": {
"CLICK_URL": "https://publisher.example.com/click/abc123"
}
}
```
**レスポンス** — マニフェストにはマクロが解決された広告配信タグアセットが含まれます。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-response.json",
"status": "completed",
"recipe_hash": "rh_scope3_9f2c7a1d5b3e",
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.example.com",
"id": "display_static",
"width": 300,
"height": 250
},
"assets": {
"ad_tag": {
"content": ""
},
"clickthrough_url": {
"url": "https://acmecorp.example.com/holiday-sale"
}
}
}
}
```
`CLICK_URL` マクロは指定した値に置換されました。`CACHEBUSTER` はセールスエージェントが配信時に解決するためのプレースホルダーとして残っています。
`recipe_hash` を、広告タグの重複排除、法的/開示の等価性の証明、またはビルド結果と配信されたデリバリーデータの結合に使わないでください。リネージとレポートには `build_variant_id` とプロモートされた `creative_id` を使います。
**クロスエージェントワークフロー**: クリエイティブ生成とメディアバイを異なるエージェントが処理する場合、クリエイティブエージェントの `build_creative` でタグ付きマニフェストを生成し、次にセールスエージェントの [`sync_creatives`](/docs/creative/task-reference/sync_creatives) でアップロードします。セールスエージェントが両方のプロトコルを実装している場合、単一のエンドポイントで行われる。[セールスエージェントのクリエイティブ機能](/docs/creative/sales-agent-creative-capabilities)を参照。
### マルチフォーマット生成
`target_format_ids` を使用して 1 回の呼び出しで複数のフォーマット向けにクリエイティブを生成します。エージェントは同じソースアセットとブリーフからフォーマットごとに 1 つのマニフェストを生成します。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-request.json",
"idempotency_key": "a1b2c3d7-0000-4000-8000-000000000003",
"message": "Create display banners for our spring campaign",
"target_format_ids": [
{
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_static",
"width": 300,
"height": 250
},
{
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_static",
"width": 728,
"height": 90
},
{
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_static",
"width": 320,
"height": 50
}
],
"brand": {
"domain": "acmecorp.com"
},
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_static"
},
"assets": {
"banner_image": {
"asset_type": "image",
"url": "https://cdn.acmecorp.com/spring-hero.png",
"width": 1200,
"height": 628
},
"headline": {
"asset_type": "text",
"content": "Spring Collection Now Available"
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://acmecorp.example.com/spring?campaign={MEDIA_BUY_ID}"
}
}
}
}
```
レスポンスは `creative_manifest`（単数）の代わりに `creative_manifests`（配列）を使用します。各マニフェストは独自の `format_id` を持つ完全なクリエイティブマニフェストで、`sync_creatives` または `preview_creative` にそのまま使用できます。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-response.json",
"status": "completed",
"creative_manifests": [
{
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_static",
"width": 300,
"height": 250
},
"assets": {
"banner_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/generated/spring_300x250.png",
"width": 300,
"height": 250
},
"headline": { "asset_type": "text", "content": "Spring Collection Now Available" },
"clickthrough_url": { "asset_type": "url", "url": "https://acmecorp.example.com/spring?campaign={MEDIA_BUY_ID}" }
}
},
{
"format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "display_static", "width": 728, "height": 90 },
"assets": { /* same structure, adapted for 728x90 */ }
},
{
"format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "display_static", "width": 320, "height": 50 },
"assets": { /* same structure, adapted for 320x50 */ }
}
]
}
```
マルチフォーマットリクエストはアトミックです。いずれかのフォーマットが失敗した場合（例: `FORMAT_NOT_SUPPORTED`）、リクエスト全体がエラーレスポンスで失敗します。レスポンス配列の順序は `target_format_ids` リクエストの順序に対応します。配列の位置または各マニフェストの `format_id` を比較してマニフェストをリクエストされたフォーマットに対応付ける。
### マルチフォーマットワークフロー
マルチフォーマットビルド後、`preview_creative` バッチモードを使用してすべての結果をプレビューします。ビルドレスポンスの `creative_manifests` の各要素が、バッチプレビューリクエストの `creative_manifest` となります。
```json theme={null}
{
"request_type": "batch",
"quality": "draft",
"requests": [
{ "creative_manifest": { /* 300x250 manifest from build response */ } },
{ "creative_manifest": { /* 728x90 manifest from build response */ } },
{ "creative_manifest": { /* 320x50 manifest from build response */ } }
]
}
```
マルチフォーマットビルドで 1 つのフォーマットをリファインするには、`target_format_id`（単数）で `build_creative` を再度呼び出し、そのフォーマットのマニフェストを渡します。すべてのフォーマットを再ビルドする必要はなく、修正が必要な 1 つだけ反復すれば良い。
`include_preview: true` を使ったマルチフォーマットリクエストは、フォーマットごとに 1 つのデフォルトプレビューを生成します。カスタム `preview_inputs` はシングルフォーマットリクエストでのみサポートされます。デバイスバリアント・異なるコンテキストなど、コンテキスト固有のプレビューが必要なマルチフォーマットビルドでは、ビルド後に別途 `preview_creative` バッチ呼び出しを使用すること。
### トランスフォーマーとバリアント
`transformer_id` でトランスフォーマーを選択し（[`list_transformers`](/docs/creative/task-reference/list_transformers) で発見）、その params にキー付けした型付き `config` を与え、`max_variants` で代替を要求します。エージェントは[バリアントレスポンス](#バリアントレスポンス)を返します: `creatives[]` で、それぞれが `variants[]` 配列を持ちます。エージェントの best-of-N の選択を表面化するには `recommended` / `rank` を読み、望むバリアントを `build_variant_id` でトラフィックします。
解像度と品質ティアは `variant_axis` ではなく `target_format_ids`（または `quality`）に載せます——バリアントは*同じ*フォーマットに対する代替です。
```javascript test=false theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { BuildCreativeResponseSchema } from '@adcp/sdk';
const result = await testAgent.buildCreative({
account: { account_id: 'acct_acme' },
transformer_id: 'audiostack_voiceover',
config: { voice: 'isaac', speaking_rate: 1.1, mastering_preset: 'podcast' },
target_format_id: { agent_url: 'https://creative.audiostack.example', id: 'audio_vo' },
creative_manifest: {
format_id: { agent_url: 'https://creative.audiostack.example', id: 'script' },
assets: { script: { asset_type: 'text', content: 'Discover the new winter collection.' } },
},
max_variants: 3,
variant_axis: { dimension: 'best_of_n', label: 'Read takes' },
keep_mode: 'keep_one',
idempotency_key: '0c1d2e3f-4a5b-6c7d-8e9f-a0b1c2d3e4f5',
});
const parsed = BuildCreativeResponseSchema.parse(result);
for (const creative of parsed.creatives ?? []) {
for (const variant of creative.variants) {
console.log(variant.build_variant_id, variant.rank, variant.recommended, variant.vendor_cost);
}
}
```
```python test=false theme={null}
import asyncio
from adcp.testing import test_agent
from adcp import BuildCreativeResponse
async def main():
result = await test_agent.build_creative(
account={"account_id": "acct_acme"},
transformer_id="audiostack_voiceover",
config={"voice": "isaac", "speaking_rate": 1.1, "mastering_preset": "podcast"},
target_format_id={"agent_url": "https://creative.audiostack.example", "id": "audio_vo"},
creative_manifest={
"format_id": {"agent_url": "https://creative.audiostack.example", "id": "script"},
"assets": {"script": {"asset_type": "text", "content": "Discover the new winter collection."}},
},
max_variants=3,
variant_axis={"dimension": "best_of_n", "label": "Read takes"},
keep_mode="keep_one",
idempotency_key="0c1d2e3f-4a5b-6c7d-8e9f-a0b1c2d3e4f5",
)
parsed = BuildCreativeResponse.model_validate(result)
for creative in parsed.creatives or []:
for variant in creative.variants:
print(variant.build_variant_id, variant.rank, variant.recommended, variant.vendor_cost)
asyncio.run(main())
```
3 つのテイクすべてに対して課金されます（`per_unit` × 3）。`keep_mode` は助言的です。保持は選択した `build_variant_id` に対する別のトラフィッキングステップです——生成されたマニフェストを [`sync_creatives`](/docs/creative/task-reference/sync_creatives) を通じてプロモートする際に、その id を `creative_id` として使います。保持されたバリアントはその後、`creative_id` がビルドリーフ id である creative レコードを遅延的に得て、[`report_usage`](/docs/accounts/tasks/report_usage) とデリバリーレポートへ流れます。
### 価格付きの有料ビルド
クリエイティブエージェントが課金し `account` が提供された場合、レスポンスには価格フィールドが含まれます。エージェントは、アカウントのレートカードと実行された作業に基づいてサーバー側で適用可能な価格オプションを選択します——バイヤーはリクエストで `pricing_option_id` を渡しません。
**単位あたりの価格（変換エージェント）**:
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-request.json",
"idempotency_key": "e5f6a7b8-c9d0-4123-e456-789abcdef012",
"account": { "account_id": "acct_acme_creative" },
"creative_id": "cr_hero_banner",
"target_format_id": {
"agent_url": "https://creative.example.com",
"id": "display_728x90"
}
}
```
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-response.json",
"status": "completed",
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.example.com",
"id": "display_728x90"
},
"assets": {
"ad_tag": {
"content": "...
"
}
}
},
"pricing_option_id": "po_standard_per_format",
"vendor_cost": 2.00,
"currency": "USD",
"consumption": {
"renders": 1
}
}
```
`pricing_option_id` は [`list_creatives`](/docs/creative/task-reference/list_creatives#pricing) のオプションの 1 つに対応します。バイヤーは照合のために [`report_usage`](/docs/accounts/tasks/report_usage) でそれを渡します。
**CPM 価格（アドサーバー）** — インプレッションが配信されたときにコストが発生するため、ビルド時の `vendor_cost` は 0 です:
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-response.json",
"status": "completed",
"creative_manifest": { "..." : "..." },
"pricing_option_id": "po_video_cpm",
"vendor_cost": 0,
"currency": "USD"
}
```
## レスポンスフォーマット
### シングルフォーマットレスポンス
リクエストで `target_format_id` を使用した場合、レスポンスには単一のクリエイティブマニフェストが含まれます。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-response.json",
"status": "completed",
"recipe_hash": "rh_winter_300x250_4c2a",
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250"
},
"assets": {
"offering_catalog": {
"asset_type": "catalog",
"type": "offering",
"catalog_id": "winter-sale"
},
"banner_image": {
"asset_type": "image",
"url": "https://cdn.example.com/generated-banner.png",
"width": 300,
"height": 250
},
"headline": {
"asset_type": "text",
"content": "50% Off Winter Sale"
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://mybrand.example.com/winter-sale?campaign={MEDIA_BUY_ID}"
}
}
}
}
```
### マルチフォーマットレスポンス
リクエストで `target_format_ids` を使用した場合、レスポンスにはクリエイティブマニフェストの配列が含まれます。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-response.json",
"status": "completed",
"creative_manifests": [
{
"format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "display_static", "width": 300, "height": 250 },
"assets": { /* ... */ }
},
{
"format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "display_static", "width": 728, "height": 90 },
"assets": { /* ... */ }
}
]
}
```
### バリアントレスポンス
リクエストが `max_creatives`、`max_variants` > 1、`variant_axis`、または `refine_from_build_variant_id` を使う場合、エージェントは `BuildCreativeVariantSuccess` 形を返します——シングルフォーマットおよびマルチフォーマットレスポンス（これらは変更されず、1 つのバリアントで 1 つのクリエイティブをビルドするときに引き続き使われます）と並ぶ 3 番目の成功形（`oneOf` の 6 のうちのメンバー 3）です。
**フォールバックなし。** `max_creatives`、`max_variants > 1`、`variant_axis`、`refine_from_build_variant_id` のいずれかを送った場合、`creatives[]` を扱わなければなりません（**MUST**）——`creative_manifest`/`creative_manifests` は返ってきません。シングル/マルチ形への自動的なダウングレードはありません。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-response.json",
"status": "completed",
"creatives": [
{
"build_creative_id": "bc_card_01",
"catalog_item_ref": { "catalog_type": "product", "item_id": "sku_winter_parka" },
"variants": [
{
"build_variant_id": "bv_card01_a",
"recipe_hash": "rh_card01_bestofn_7b91",
"creative_manifest": { "format_id": { "agent_url": "https://creative.example.com", "id": "display_300x250" }, "assets": { "...": "..." } },
"variant_axis_value": "take_1",
"recommended": true,
"rank": 1,
"pricing_option_id": "po_per_image",
"vendor_cost": 0.40,
"currency": "USD",
"consumption": { "images_generated": 1 }
},
{
"build_variant_id": "bv_card01_b",
"recipe_hash": "rh_card01_bestofn_7b91",
"creative_manifest": { "format_id": { "agent_url": "https://creative.example.com", "id": "display_300x250" }, "assets": { "...": "..." } },
"variant_axis_value": "take_2",
"recommended": false,
"rank": 2,
"pricing_option_id": "po_per_image",
"vendor_cost": 0.40,
"currency": "USD",
"consumption": { "images_generated": 1 }
}
]
}
],
"items_total": 150,
"items_returned": 5,
"vendor_cost": 4.00,
"currency": "USD"
}
```
*上記の `creatives[]` 配列は、返された 5 グループのうちの 1 つに省略されています。集計の `vendor_cost` $4.00 は、全 5 グループ × 2 バリアント × $0.40 をカバーします——これは表示されたリーフだけでなく、生成されたすべてのリーフの `vendor_cost` の合計に等しくなります。*
* **creatives\[]**: ビルドされたクリエイティブグループごとに 1 エントリ。`max_creatives` を使うと、サンプリングされたカタログアイテムごとに 1 エントリになります（`catalog_item_ref` がどのアイテムかを識別）。カタログのファンアウトがない場合は単一のエントリです。これを生成されたグループの集合として扱い、各グループの `variants[]` 内で代替から選びます。
* **creatives\[].build\_creative\_id**: このレスポンス内でビルドされたクリエイティブを識別します。
* **creatives\[].catalog\_item\_ref**: カタログのファンアウトで存在——`item_id`（と任意の `catalog_type`）でソースカタログアイテムを識別するオブジェクト。
* **creatives\[].signal\_condition**: シグナルのファンアウトで存在——このクリエイティブグループが対象とする SignalTargeting 条件（例: weather=rain）。セールス側のパッケージターゲティングと `signal_ref` のアイデンティティを共有するため、セールスエージェントが互換性のない割り当てを照合・拒否できます。
* **creatives\[].errors\[]**: *失敗した*カタログアイテムでのみ存在——カタログのファンアウトは非アトミックなので、失敗したアイテムは `errors[]` を運び `variants[]` を持たない `creatives[]` エントリとして返され、バッチを失敗させません。
* **creatives\[].variants\[]**: このクリエイティブグループに対して生成された、選ぶための代替。長さは最大でも `max_variants`。各バリアントは独自の完全な `creative_manifest` を運びます。
* **variants\[].build\_variant\_id**: 単一のバリアントを識別——リーフレベルの**リネージアンカー**。これは**独自の名前空間**です——`preview_id`（`preview_creative` のレンダー）や配信された `variant_id`（デリバリー時の識別子）をここで再利用しないでください。選択したビルドは、その `build_variant_id` を渡してトラフィックします。
* **variants\[].recipe\_hash**: リーフを生成したビルド決定入力に対する、任意の ETag スタイルのアイデンティティ。エージェントが計算し、不透明で、同じエージェント内でのみ比較可能。同じソースレシピからの best-of-N リーフは値を共有すべきです（SHOULD）。キャッシュの透明性、コスト回避のヒント、レシピレベルのグルーピングに有用ですが、出力の同一性でも、法的/開示の等価性でも、ビルドからデリバリーへの結合でもありません。
* **variants\[].parent\_build\_variant\_id**: リファインされたバリアントでのみ存在（[リファインメント](#リファインメント)）——リファイン元のソースの `build_variant_id`。第一世代のビルドでは不在。
* **variants\[].variant\_axis\_value**: このバリアントが表す `variant_axis` 次元の値（例: 声、テーマ）。
* **variants\[].recommended / rank**: エージェントの best-of-N の順序付け。`recommended: true` が最上位の選択を、`rank` が順序を示します。
* **variants\[].eval**: `evaluator` が提供された場合に存在——ゲート後にランク付けするパイプラインからのリーフごとの評価ブロック。評価器の `feature_id` にキー付けされた `features[]` を含みます。
* **items\_total / items\_returned**: カタログのファンアウトのカーディナリティ。`items_returned` \< `items_total` は、`max_creatives` または `max_creatives_limit` によるサンプリング/クランプを示します。
* **vendor\_cost**（トップレベル）: 生成されたすべてのリーフにわたる集計コスト。個々の `variants[].vendor_cost` の合計。
**ビルド時のバリアントはデリバリーのバリアントではありません。** ここでの `build_variant_id` は、生成した代替に対する配信前のハンドルです。これは、[`get_creative_delivery`](/docs/creative/task-reference/get_creative_delivery) の配信された `variant_id`（*配信されたクリエイティブの実行*を識別）とは異なる名前空間です。ビルド時のバリアントは、保持してトラフィックした時点で初めてデリバリーのバリアントになります。
**解像度と品質ティアはバリアントではありません。** 複数のサイズや品質レベルはフォーマット軸に属します——`variant_axis` の値としてではなく、`target_format_ids`（または `quality`）として渡します。バリアントは*同じフォーマットに対する*代替です（異なる声、テーマ、または best-of-N のテイク）。
### リファインメント
会話的なリファインメントは、以前のバリアントを自由形式の指示で再ビルドします——「もっと暖かく」「CTA を引き締めて」。型付き `config` の面は設計上閉じているので、自由形式の意図は、すでに存在する**開かれた**面に乗ります: `message` フィールド（その説明はすでに\*「リファインメント時は変更内容を記述します」\*）。したがってリファインメントは新しいタスクではなく——1 つ追加の入力を伴う `build_creative` です:
* `refine_from_build_variant_id`（以前のリーフの `build_variant_id`）に加えて、`message` に指示、任意の `config` デルタを渡します。
* エージェントはそのリーフから再ビルドし、それぞれ `parent_build_variant_id` をソースに設定した**新しい**バリアントを返します。リファインメントは**決して変更ではありません**——親リーフは変更されず、新しいリーフは独自の `build_variant_id`（およびトラフィッキング時に独自の `creative_id`）を得ます。
* `transformer_id` とターゲットフォーマットは親から**継承**され、繰り返しません。親と異なる `transformer_id` やターゲットフォーマットを渡すことは `INVALID_REQUEST` です。`config` は親の config に対する**デルタ**として適用されます。
* `max_variants` / `variant_axis` と合成されますが（例: 「もっと暖かい 3 テイク」→ 3 つのリファインされたリーフ）、`max_creatives` / カタログのファンアウトとは合成**されません**——カタログではなく、生成された 1 つのクリエイティブをリファインします。
* エージェントが `creative.supports_refinement: true` を表明する必要があります（エージェントが定めた期間、生成されたリーフを保持します）。何も保持しないエージェントは `UNSUPPORTED_FEATURE` を返します。代わりに変換パス（`creative_manifest` + `message`）を通じてバイヤー保持のマニフェストをリファインしてください。未知の、または保持されなくなった参照は、`error.field` を `refine_from_build_variant_id` に設定した `REFERENCE_NOT_FOUND` を返します。
バリアントビルドだけでなく、あらゆるビルドをリファインできます: シングルフォーマットの `BuildCreativeSuccess` は、任意の `build_variant_id`（エージェントがリファインメントをサポートするときに存在）を運び、それを `refine_from_build_variant_id` として渡します。出力ごとにリファイン可能なリーフが必要なマルチフォーマットビルドは、素の `creative_manifests[]` 配列がリーフ id を運ばないため、バリアント形（`max_variants`）を要求すべきです。
AI 派生物のアトリビューションはマニフェストの既存の `provenance` に乗ります。`parent_build_variant_id` はリネージのエッジのみを運びます（リファインメントはツリーへ連鎖します）。
```json test=false theme={null}
{
"refine_from_build_variant_id": "bv_card01_a",
"message": "Warmer lighting, and move the logo to the lower-right.",
"max_variants": 3,
"account": { "account_id": "acct_acme" },
"idempotency_key": "7f2a1b3c-4d5e-6f70-8192-a3b4c5d6e7f8"
}
```
### 支出コントロール
ファンアウトとリファインメントは、独立して課金される多くのリーフ（`max_creatives` × `max_variants`）を生成でき、`per_unit` 価格は*レート*を与えますが事前に*単位数*を与えません（6 秒のボイスオーバーと 60 秒のものは、同じレートで 10 倍のコストになります）。`creative.supports_spend_controls` でゲートされた 2 つのオプトインコントロール:
* **まず見積もる（`mode: "estimate"`）。** ドライラン: エージェントは何も生成せず課金もせず、`cost_low`/`cost_high` の帯（および `basis`: `fixed` = 正確、`estimated_units` = 生成的な予測、`cpm_deferred` = 配信時にコストが発生）を持つ `BuildCreativeEstimate` を返します。帯が要となる部分です——セラーがあなたの実際の入力から導出するので、単位数を推測する必要がありません。
* **呼び出しを上限する（`max_spend: { amount, currency }`）。** ハードストップ: エージェントは、次のリーフが集計 `vendor_cost` を `amount` 超に押し上げるまでリーフを生成し、その後 `budget_status: "capped"` と `errors[]` の助言的な `BUDGET_CAP_REACHED` を伴う部分的な `BuildCreativeVariantSuccess` を返します——返されたすべてのリーフは実在し課金され、生成されたものは何も破棄されません。リーフ粒度の不足は `leaves_returned` \< `leaves_total` です（`items_returned`/`items_total` ではありません。これらはカタログアイテムを数え、バリアントのみやアイテム途中の上限を捉えません）。`BUDGET_CAP_REACHED` の助言が権威ある上限シグナルです。最初のリーフでさえ上限を超える場合、呼び出しは終端の `BUDGET_CAP_REACHED` で失敗します。`currency` はレートカードと一致しなければならず（FX なし）、さもなければリクエストは `INVALID_REQUEST`（`error.field: max_spend.currency`）で拒否されます。`max_spend` は**ビルド時**の `vendor_cost` のみを制限します——CPM 価格のビルド（`basis: cpm_deferred`）はビルド時に 0 で配信時に発生するので、上限は決して働きません。CPM のファンアウトは代わりに `max_creatives` で制限してください。
これらは合成されます: 見積もって `cost_high` を得て、その後 `max_spend` = `cost_high` × 安全マージンで実行します（CPM ビルドは例外——ビルド時の `cost_high` は 0）。`max_spend` は**単一の呼び出し**を上限とします。自律的な**リファインメントループ**を制限するには、呼び出しをまたいで集計 `vendor_cost` を追跡し、発行を止めます（このリビジョンではバイヤーの責任——プロトコルレベルのセッション予算はワーキンググループに先送り）。
`max_spend` と `mode: "estimate"` は、エージェントが `creative.supports_spend_controls` を表明する必要があります。さもなければ `UNSUPPORTED_FEATURE` で拒否されます。これらは `bills_through_adcp: true` のときにのみ意味を持ちます（帯域外の請求者には上限すべき AdCP コストがありません）。
### 見積もりレスポンス
`mode: "estimate"` のリクエストは、`BuildCreativeEstimate` 形（`oneOf` の 6 のうちのメンバー 4）を返します——何も生成せず課金もせず、予測されたコスト帯だけ:
```json test=false theme={null}
{
"$schema": "/schemas/media-buy/build-creative-response.json",
"status": "completed",
"mode": "estimate",
"estimate": {
"items_total": 150,
"items_to_produce": 5,
"variants_per_item": 3,
"leaves_total": 15,
"currency": "USD",
"cost_low": 6.00,
"cost_high": 9.00,
"cost_expected": 7.50,
"basis": "estimated_units"
},
"expires_at": "2026-06-01T00:00:00Z"
}
```
* **estimate.leaves\_total** = `items_to_produce` × `variants_per_item`（`signal_conditions` が送られた場合は × `conditions_total`）——`mode: "execute"` が生成する課金対象リーフの数。
* **estimate.cost\_low / cost\_high / cost\_expected**: 予測された集計コスト帯。セラーがあなたの実際の入力から導出します。
* **estimate.basis**: `fixed`（フォーマットあたりのフラット——`cost_low == cost_high`、正確）、`estimated_units`（生成的な `per_unit`。帯は単位数の不確実性を反映）、または `cpm_deferred`（CPM——ビルド時コストは 0、配信時に発生するので帯は 0）。
* **estimate.per\_leaf**（任意）: リーフごとの内訳。
* 見積もりはこのリビジョンでは**助言的/非拘束**です（拘束力のある見積もりはワーキンググループに先送り）。
### フィールド説明
* **creative\_manifest**: （シングルフォーマット）`sync_creatives` または `preview_creative` で使用できる完全なクリエイティブマニフェスト
* **creative\_manifests**: （マルチフォーマット）リクエストされたフォーマットごとの完全なクリエイティブマニフェストの配列。各要素が独自の `format_id` を持ちます。
* **format\_id**: ターゲットフォーマット（リクエストされたフォーマットと一致します）
* **assets**: アセットキーからアセットコンテンツへのマップ — クリエイティブコンテンツ（画像・テキスト・URL）、カタログ、ブリーフ、フォーマットが必要とするその他すべてを含みます
* **expires\_at**: オプション。マニフェスト内の生成されたアセット URL の有効期限を示す ISO 8601 タイムスタンプ。すべての生成済みアセットの中で最も早い有効期限に設定されます。この時刻を過ぎたら新しい URL を取得するためにクリエイティブを再ビルドすること。マニフェストに有効期限のある URL が含まれない場合（例: 純粋なテキスト生成やアセンブリのみの変換）は存在しません。
* **preview**: オプション。リクエストで `include_preview` が true で、エージェントがインラインプレビューをサポートしている場合に存在します。`preview_creative` のシングルレスポンスと同じコンテンツフィールド（`previews`、`interactive_url`、`expires_at`）を含むが、`response_type` ディスクリミネーターは除く。クライアントが同じプレビューレンダリングロジックを再利用できます。プレビュー URL は `preview_creative` と同じ耐久性契約に従います: `expires_at` まで、または有効期限が存在しない場合は明示的な帯域外の失効まで、参照解決可能なままです。シングルフォーマットレスポンスでは、`previews[]` の各エントリが `preview_inputs` の入力セットに対応します。マルチフォーマットレスポンスでは、各エントリに `format_id` が含まれ、リクエストされたフォーマットの 1 つに対応する（フォーマットごとに 1 つのデフォルトプレビュー。`preview_inputs` は無視されます）。
* **preview\_error**: オプション。`include_preview` が true だったがプレビュー生成が失敗した場合に存在する標準エラーオブジェクト（`code`、`message`、`recovery`）。`recovery` フィールドは失敗が `transient`（後でリトライ）、`correctable`、または `terminal` のいずれかを示します。「エージェントがインラインプレビューをサポートしない」（フィールドが存在しない、エラーなし）と「プレビュー生成が失敗した」（フィールドが存在し、構造化エラーあり）を区別します。
### コンプライアンスエラー
マニフェストに `compliance` 要件を持つ brief アセットが含まれており、クリエイティブエージェントがその要件を満たせない場合、エージェントは部分的な成功ではなくエラーを返さなければなりません（MUST）。未充足のディスクロージャーはハードな失敗です。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-response.json",
"status": "completed",
"errors": [
{
"code": "COMPLIANCE_UNSATISFIED",
"message": "Required disclosure cannot be rendered in this format",
"field": "creative_manifest.assets.brief.compliance.required_disclosures[0]",
"details": {
"disclosure_text": "Past performance is not indicative of future results.",
"position": "footer",
"reason": "Format display_mobile_320x50 does not support footer position"
},
"suggestion": "Use a format that supports footer disclosures, or change position to 'overlay'"
}
]
}
```
クリエイティブエージェントはクリエイティブを生成する前に、すべての `required_disclosures` をターゲットフォーマットで満たせることをバリデートしなければなりません（MUST）。いずれかのディスクロージャーを指定通りに配置できない場合、リクエスト全体が失敗します。これにより、規制対象のクリエイティブが必要な法的テキストなしに配信されることを防ぐ。
## レスポンスのタイミング
クリエイティブエージェントがどう応答するかは、操作にどれだけ時間がかかるかによります:
| 想定される所要時間 | ステータス | 呼び出し元の体験 |
| ----------------------- | ----------- | ----------------------------------------------------------- |
| 30 秒未満 | `completed` | 結果を直接返却——同期 |
| 30 秒超、サーバーが能動的に処理中 | `working` | サーバーが処理を続ける間、帯域外のステータス更新。呼び出し元は接続を保持——彼らの視点では依然として同期 |
| 外部依存（人によるレビュー、承認）でブロック中 | `submitted` | 真の非同期——呼び出し元は `push_notification_config` でウェブフックを設定して先に進むべき |
クリエイティブエージェントは、関与する作業に基づいてどの経路を取るかを決めます。ライブラリ取得は即時。単純な変換は数秒。AI 生成はさまざま——手早いバナーは 10 秒で完了するかもしれず、複雑な動画コンポジションは数分かかるかもしれません。
### `working` はポーリングのトリガーではなく進捗シグナル
サーバーが 30 秒超かかると想定するが能動的に処理している場合、帯域外の MCP ステータス更新として `working` を送ります。これは、呼び出し元をポーリングやウェブフックのパターンに切り替えさせることなく、クライアントに情報を伝え続けます（「取り組んでいます」）。接続は開いたままで、結果は準備ができたときに届きます。
### 非同期にするとき
`submitted` は、操作がサーバーの制御外の何かでブロックされていることを意味します:
* **人によるクリエイティブレビュー** — ブランドガイドラインが返却前に承認を要求
* **外部の承認ワークフロー** — サードパーティのコンプライアンスまたは法的レビュー
これらのケースでは、結果を受け取るために `push_notification_config` でウェブフックを設定します。[非同期オペレーション](/docs/building/by-layer/L3/async-operations)と[プッシュ通知](/docs/building/by-layer/L3/webhooks)を参照してください。
### ヒューマンインザループ
エージェントは、人間の入力が必要なときに `status: "input-required"` を返す場合があります——例えば、ブランドガイドラインがクリエイティブ承認を要求する場合や、エージェントがクリエイティブ方向性の明確化を必要とする場合などです。
```json theme={null}
{
"reason": "CREATIVE_DIRECTION_NEEDED"
}
```
**理由コード:**
* `APPROVAL_REQUIRED` — クリエイティブを確定する前に人間の承認が必要
* `CREATIVE_DIRECTION_NEEDED` — クリエイティブブリーフまたは方向性について明確化が必要
* `ASSET_SELECTION_NEEDED` — アセットの選択肢の中から呼び出し元に選択させる必要があります
ライブラリ取得モード（`creative_id` を使用）は通常同期的です。クリエイティブがすでに存在しており、タグ生成のみが必要なためです。非同期が最も一般的なのは生成および変換モードです。
## ワークフロー統合
### 一般的な生成ワークフロー
1. **ビルド**: `build_creative` を使用してマニフェストを生成・変換します
2. **プレビュー**: `preview_creative` を使用してレンダリングを確認する（[preview\_creative](/docs/creative/task-reference/preview_creative) を参照）
3. **シンク**: `sync_creatives` を使用して確定したクリエイティブをトラフィッキングします
ビルドリクエストに `include_preview: true` を設定することで、ステップ 1 と 2 を組み合わせることができます。エージェントがサポートしている場合、レスポンスにはマニフェストと共に `preview` オブジェクトが含まれ、余分なラウンドトリップが不要になります。エージェントがインラインプレビューをサポートしない場合、フィールドは単純に省略され、別途 `preview_creative` 呼び出しにフォールバックします。リクエストした際に `preview` が存在すると仮定するのではなく、常にその存在を確認すること。
`preview_quality` を使用してビルド品質から独立してレンダーの忠実度を制御します。例えば、`quality: "draft"`（高速なコンセプト生成）でビルドしながら、`preview_quality: "production"`（ステークホルダーにレイアウトを見せるためのフルフィデリティレンダー）でプレビューします。`preview_quality` を省略した場合、エージェントが独自のデフォルトを使用します。
```json theme={null}
// Build at draft quality, but preview at production quality for stakeholder review
{
"message": "Create a display banner for our winter sale",
"target_format_id": {"agent_url": "...", "id": "display_300x250_generative"},
"brand": { "domain": "mybrand.com" },
"quality": "draft",
"include_preview": true,
"preview_quality": "production",
"creative_manifest": {
"format_id": {"agent_url": "...", "id": "display_300x250_generative"},
"assets": {
"product_catalog": {
"asset_type": "catalog",
"type": "product",
"catalog_id": "winter-products"
}
}
}
}
// Or: Build first, preview separately
// Step 1: Build
{
"message": "Create a display banner for our winter sale",
"target_format_id": {"agent_url": "...", "id": "display_300x250_generative"},
"brand": { "domain": "mybrand.com" },
"creative_manifest": {
"format_id": {"agent_url": "...", "id": "display_300x250_generative"},
"assets": {
"product_catalog": {
"asset_type": "catalog",
"type": "product",
"catalog_id": "winter-products"
}
}
}
}
// Step 2: Preview (using the output manifest from step 1)
{
"request_type": "single",
"format_id": {"agent_url": "...", "id": "display_300x250"},
"creative_manifest": {
/* output from build_creative - includes all assets */
},
"inputs": [{"name": "Desktop view"}, {"name": "Mobile view"}]
}
// Step 3: Sync (if preview looks good)
{
"creative_manifests": [{ /* approved manifest from build_creative */ }]
}
```
**重要なポイント**: マニフェストがすべてを運ぶ。ブリーフ・カタログ・画像・テキスト — すべてがアセットマップに存在し、入力から出力まで受け渡されます。各ステップで個別に渡す必要はない。
## 例
### 例 1: 純粋な生成（ジェネレーティブフォーマット）
ジェネレーティブフォーマットを使用してスクラッチからクリエイティブを生成します。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-request.json",
"idempotency_key": "a1b2c3d8-0000-4000-8000-000000000004",
"message": "Create a display banner for our winter sale. Use warm colors and emphasize the 50% discount",
"target_format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250_generative"
},
"brand": {
"domain": "mybrand.com"
},
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250_generative"
},
"assets": {
"offering_catalog": {
"asset_type": "catalog",
"type": "offering",
"items": [
{
"offering_id": "winter-sale",
"name": "Winter Sale Collection",
"description": "50% off all winter items"
}
]
}
}
}
}
```
**レスポンス**:
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-response.json",
"status": "completed",
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250"
},
"assets": {
"offering_catalog": {
"asset_type": "catalog",
"type": "offering",
"catalog_id": "winter-sale"
},
"banner_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/generated/banner_12345.png",
"width": 300,
"height": 250
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://mybrand.example.com/winter-sale?campaign={MEDIA_BUY_ID}"
}
}
}
}
```
### 例 2: フォーマット変換
既存の 728x90 リーダーボードを 300x250 バナーに変換します。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-request.json",
"idempotency_key": "a1b2c3d9-0000-4000-8000-000000000005",
"message": "Adapt this leaderboard creative to a 300x250 banner format",
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_728x90"
},
"assets": {
"banner_image": {
"asset_type": "image",
"url": "https://cdn.mybrand.com/leaderboard.png",
"width": 728,
"height": 90
},
"headline": {
"asset_type": "text",
"content": "Spring Sale - 30% Off Everything"
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://mybrand.example.com/spring?campaign={MEDIA_BUY_ID}"
}
}
},
"target_format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250"
}
}
```
**レスポンス**:
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-response.json",
"status": "completed",
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250"
},
"assets": {
"banner_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/resized/banner_67890.png",
"width": 300,
"height": 250
},
"headline": {
"asset_type": "text",
"content": "Spring Sale - 30% Off"
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://mybrand.example.com/spring?campaign={MEDIA_BUY_ID}"
}
}
}
}
```
### 例 3: 特定の指示を含む変換
特定のデザイン変更を伴うモバイル向けへの変換。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-request.json",
"idempotency_key": "a1b2c3da-0000-4000-8000-000000000006",
"message": "Make this mobile-friendly: increase text size, simplify the layout, and make the CTA button more prominent",
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x600"
},
"assets": {
"background_image": {
"asset_type": "image",
"url": "https://cdn.mybrand.com/bg.jpg",
"width": 300,
"height": 600
},
"headline": {
"asset_type": "text",
"content": "Discover Our New Collection"
},
"body_text": {
"asset_type": "text",
"content": "Shop the latest styles with free shipping on orders over $50"
},
"cta_text": {
"asset_type": "text",
"content": "Shop Now"
}
}
},
"target_format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_mobile_320x50"
}
}
```
**レスポンス**:
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-response.json",
"status": "completed",
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_mobile_320x50"
},
"assets": {
"banner_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/mobile/banner_mobile_123.png",
"width": 320,
"height": 50
},
"headline": {
"asset_type": "text",
"content": "New Collection - Shop Now"
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://mybrand.example.com/new?campaign={MEDIA_BUY_ID}"
}
}
}
}
```
### 例 4: クリエイティブブリーフを使った生成
`brand` とマニフェストの brief アセットを通じて構造化されたキャンペーンコンテキストを使用してクリエイティブを生成します。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-request.json",
"idempotency_key": "a1b2c3db-0000-4000-8000-000000000007",
"message": "Create a display banner for the holiday campaign targeting gift shoppers",
"target_format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250_generative"
},
"brand": {
"domain": "acmecorp.com"
},
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250_generative"
},
"assets": {
"brief": {
"asset_type": "brief",
"name": "Holiday Sale 2025",
"objective": "conversion",
"audience": "Holiday gift shoppers aged 25-55",
"territory": "festive savings",
"messaging": {
"headline": "Holiday Deals Are Here",
"cta": "Shop Now",
"key_messages": [
"Up to 50% off select items",
"Free shipping on orders over $50"
]
},
"reference_assets": [
{
"url": "https://cdn.acmecorp.com/holiday-mood-board.pdf",
"role": "mood_board",
"description": "Holiday campaign mood board with festive color palette"
}
]
},
"offering_catalog": {
"asset_type": "catalog",
"type": "offering",
"items": [
{
"offering_id": "holiday-sale",
"name": "Holiday Sale Collection",
"description": "Up to 50% off select holiday items"
}
]
}
}
}
}
```
### 例 5: コンプライアンス要件を含む生成
規制上のディスクロージャーと禁止クレームを含む金融サービスのクリエイティブを生成します。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-request.json",
"idempotency_key": "a1b2c3dc-0000-4000-8000-000000000008",
"message": "Create a display banner promoting retirement planning advisory services",
"target_format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250_generative"
},
"brand": {
"domain": "pinnaclewealth.com"
},
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250_generative"
},
"assets": {
"brief": {
"asset_type": "brief",
"name": "Retirement Advisory Q1 2026",
"objective": "consideration",
"audience": "Pre-retirees aged 50-65 with investable assets",
"territory": "trusted financial guidance",
"messaging": {
"headline": "Plan Your Retirement with Confidence",
"cta": "Schedule a Consultation",
"key_messages": [
"Personalized retirement planning",
"Tax-efficient investment strategies"
]
},
"compliance": {
"required_disclosures": [
{
"text": "Past performance is not indicative of future results.",
"position": "footer",
"jurisdictions": ["US"],
"regulation": "SEC Rule 156"
},
{
"text": "Securities offered through Pinnacle Wealth Securities, LLC. Member FINRA/SIPC.",
"position": "footer",
"jurisdictions": ["US"],
"regulation": "FINRA Rule 2210"
},
{
"text": "Capital at risk. The value of investments can go down as well as up.",
"position": "prominent",
"jurisdictions": ["GB"],
"regulation": "FCA COBS 4.5"
},
{
"text": "Pinnacle Wealth Advisors is a registered investment adviser.",
"position": "footer"
}
],
"prohibited_claims": [
"guaranteed returns",
"risk-free investment",
"outperform the market"
]
}
}
}
}
}
```
コンプライアンス要件は管轄によって異なります。米国では SEC が義務付けるディスクロージャーが必要で、英国では FCA が義務付けるリスク警告が必要です。3 番目のディスクロージャー（`jurisdictions` なし）はグローバルに適用されます。`prohibited_claims` 配列は、生成されたコピーで避けるべきクレームをクリエイティブエージェントに伝える。
### 例 6: ブリーフと商品カタログを使ったコマースメディア
キャンペーンコンテキスト・コンプライアンスディスクロージャー・同期された商品カタログを含むスポンサー商品カルーセルを生成します。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-request.json",
"idempotency_key": "a1b2c3dd-0000-4000-8000-000000000009",
"message": "Create a product carousel highlighting the top 4 sale items",
"target_format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "sponsored_product_carousel"
},
"brand": {
"domain": "novabrands.com"
},
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "sponsored_product_carousel"
},
"assets": {
"brief": {
"asset_type": "brief",
"name": "Spring Sale 2026",
"objective": "conversion",
"audience": "Value-conscious shoppers aged 25-45",
"messaging": {
"headline": "Spring Sale — Up to 40% Off",
"cta": "Shop Now"
},
"compliance": {
"required_disclosures": [
{
"text": "Sponsored",
"position": "prominent"
},
{
"text": "Prices may vary by location. See store for details.",
"position": "footer"
}
]
}
},
"product_catalog": {
"asset_type": "catalog",
"type": "product",
"catalog_id": "spring_sale_2026"
}
}
}
}
```
ブリーフと商品カタログはマニフェストの `assets` マップに一緒に存在します。フォーマットは `brief` と `catalog` の両方のアセットタイプを宣言します。バイイングエージェントは `list_creative_formats` でこれを検出し、送信前に必要なカタログを同期します。
### 例 7: インラインプレビュー付きビルド
クリエイティブをビルドし、同一レスポンスでプレビューレンダリングを取得します。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-request.json",
"idempotency_key": "a1b2c3de-0000-4000-8000-00000000000a",
"message": "Create a banner for our spring campaign",
"target_format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250_generative"
},
"brand": {
"domain": "novabrands.com"
},
"include_preview": true,
"preview_inputs": [
{ "name": "Default" },
{ "name": "Dark mode", "macros": { "COLOR_SCHEME": "dark" } }
],
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250_generative"
},
"assets": {
"offering_catalog": {
"asset_type": "catalog",
"type": "offering",
"items": [
{
"offering_id": "spring-promo",
"name": "Spring Collection",
"description": "30% off new arrivals"
}
]
}
}
}
}
```
**レスポンス**（エージェントがインラインプレビューをサポートしている場合）:
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-response.json",
"status": "completed",
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250"
},
"assets": {
"offering_catalog": {
"asset_type": "catalog",
"type": "offering",
"catalog_id": "spring-promo"
},
"banner_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/generated/spring_abc123.png",
"width": 300,
"height": 250
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://novabrands.com/spring"
}
}
},
"preview": {
"previews": [
{
"preview_id": "prev_default",
"renders": [
{
"render_id": "r1",
"output_format": "url",
"preview_url": "https://preview.creative-agent.com/abc123/default",
"role": "primary",
"dimensions": { "width": 300, "height": 250 }
}
],
"input": { "name": "Default" }
},
{
"preview_id": "prev_dark",
"renders": [
{
"render_id": "r2",
"output_format": "url",
"preview_url": "https://preview.creative-agent.com/abc123/dark",
"role": "primary",
"dimensions": { "width": 300, "height": 250 }
}
],
"input": { "name": "Dark mode", "macros": { "COLOR_SCHEME": "dark" } }
}
],
"expires_at": "2026-03-13T06:00:00Z"
},
"expires_at": "2026-03-13T06:00:00Z"
}
```
`preview` オブジェクトには `preview_creative` のシングルレスポンスと同じコンテンツフィールド（`previews`、`interactive_url`、`expires_at`）が含まれます。エージェントがインラインプレビューをサポートしない場合、このフィールドは存在しません。バイヤーエージェントは別途 `preview_creative` 呼び出しにフォールバックします。プレビュー生成が失敗した場合、レスポンスには標準エラーオブジェクト（`code`、`message`、`recovery`）を持つ `preview_error` が含まれます。
### 例 8: アイテム制限付きドラフト生成
大規模カタログからドラフト品質のクリエイティブを生成し、アイテム数を上限設定します。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-request.json",
"idempotency_key": "a1b2c3df-0000-4000-8000-00000000000b",
"message": "Create hero images for our top sale items",
"target_format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "sponsored_product_carousel"
},
"brand": {
"domain": "novabrands.com"
},
"quality": "draft",
"item_limit": 4,
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "sponsored_product_carousel"
},
"assets": {
"product_catalog": {
"asset_type": "catalog",
"type": "product",
"catalog_id": "spring_sale_2026"
}
}
}
}
```
カタログには数百の商品が含まれる場合があるが、`item_limit: 4` により生成されるヒーロー画像は 4 枚のみとなります。`quality: "draft"` はレビュー用の高速・低忠実度の出力を生成します。
**レスポンス**:
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-response.json",
"status": "completed",
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "sponsored_product_carousel"
},
"assets": {
"product_catalog": {
"asset_type": "catalog",
"type": "product",
"catalog_id": "spring_sale_2026"
},
"card_1_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/draft/card1_abc123.jpg",
"width": 400,
"height": 400
},
"card_2_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/draft/card2_def456.jpg",
"width": 400,
"height": 400
},
"card_3_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/draft/card3_ghi789.jpg",
"width": 400,
"height": 400
},
"card_4_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/draft/card4_jkl012.jpg",
"width": 400,
"height": 400
}
}
},
"expires_at": "2026-03-02T06:00:00Z"
}
```
`expires_at` フィールドは生成された CDN URL の有効期限を示します。この時刻を過ぎたら新しい URL を取得するために再ビルドすること。方向性が承認されたら、最終レンダーのために出力マニフェストを `quality: "production"` で再送信します。
## 主要コンセプト
### ブランドとクリエイティブブリーフの違い
| | ブランド | クリエイティブブリーフ |
| ---------- | ------------------------------------- | --------------------------------------- |
| **スコープ** | ブランドアイデンティティ | キャンペーンコンテキスト |
| **ライフスパン** | キャンペーンをまたいで安定 | キャンペーンまたはフライトに固有 |
| **内容** | カラー・ロゴ・フォント・トーン | オーディエンス・テリトリー・メッセージ・コンプライアンス・リファレンスアセット |
| **法的事項** | ブランドレベルの免責事項（常時適用） | キャンペーン固有の規制上のディスクロージャー（地域・製品ベース） |
| **ソース** | ブランドレジストリ / `/.well-known/brand.json` | エージェンシーまたはブランドチーム |
| **格納場所** | ドメインルックアップで解決 | マニフェストのアセットマップ（`assets.brief`） |
どちらもオプションです。`brand` はドメインの `/.well-known/brand.json` 経由で解決される安定したブランドアイデンティティ（カラー・ロゴ・トーン）を提供します。ブリーフはマニフェストのアセット（`assets.brief`）であるため、再生成・リサイズ・監査を通じてクリエイティブと共に移動します。`message` フィールドはリクエストごとの自然言語の指示を提供します。
**優先順位**: `brand` パラメーターはクリエイティブレンダリングコンテキスト（カラー・ロゴ・トーン）の権威あるソースです。
**レイヤリング**: マニフェストの brief アセットは構造化された方向性を提供し、リクエストの `message` はリクエストごとの自然言語のオーバーライドを提供します。両方が競合する方向性を提供する場合、`message` が最も具体的な指示として優先されます。
### 変換モデル
`build_creative` は**マニフェストイン、マニフェストアウト**のモデルに従う。
* 入力: クリエイティブマニフェスト（最小限または完全 — すべてがアセットに存在します）
* 処理: `message` とマニフェストコンテンツに基づいて変換・生成します
* 出力: プレビューまたは同期に使用できるターゲットクリエイティブマニフェスト（ブリーフが引き継がれる）
### 純粋な生成と変換の違い
* **純粋な生成**: format\_id だけを持つ最小限の `creative_manifest`、カタログアセット（フォーマットがカタログアイテムをレンダーする場合）、および必要なシードアセットを提供します。クリエイティブエージェントは `message` をガイドとして使用してスクラッチから出力アセットを生成します。
* **変換**: すべての既存アセットを含む完全な `creative_manifest` を提供します。クリエイティブエージェントは既存アセットをターゲットフォーマットに適応させ、オプションで `message` のガイダンスに従う。
### 他のタスクとの統合
1. **build\_creative** → マニフェストを生成する（オプションで `include_preview` 経由のインラインプレビュー付き）
2. **preview\_creative** → マニフェストを個別にレンダーする（[preview\_creative](/docs/creative/task-reference/preview_creative) を参照）
3. **sync\_creatives** → 確定したマニフェストをトラフィッキングします
`include_preview: true` を使用してビルドとプレビューを 1 回の呼び出しに組み合わせます。エージェントがサポートしない場合、レスポンスは単純に `preview` フィールドを省略します。別途 `preview_creative` 呼び出しにフォールバックします。どちらの場合も、プレビューコンテンツフィールド（`previews`、`interactive_url`、`expires_at`）は同一です。
この分離により以下が可能になります。
* 一度ビルドして、異なるコンテキストで複数回プレビューします
* 再同期せずにビルドを反復します
* トラフィッキングにコミットする前にプレビューします
### 反復的なリファインメント
`build_creative` はモードフラグなしでマルチターンの反復をサポートします。フィールドの存在と組み合わせがオペレーションを決定します。
* **生成**: `message` + 最小限の `creative_manifest`（空またはシードアセット）+ `target_format_id`
* **変換**: 完全な `creative_manifest` + `message` + `target_format_id`
* **ライブラリ取得**: `creative_id` + `target_format_id` + オプションの `macro_values`
* **リファインメント**: 前の出力を `creative_manifest` として + 変更内容を示す新しい `message`
リファインするには、前のレスポンスの `creative_manifest` を新しい `message` と共に入力として渡します。または、brief アセット（`assets.brief`）を更新してクリエイティブ方向性を変更します。ブリーフはクリエイティブがどうあるべきかについてのバイヤーが所有する信頼のソースです。
```json theme={null}
{
"$schema": "/schemas/media-buy/build-creative-request.json",
"idempotency_key": "a1b2c3e0-0000-4000-8000-00000000000c",
"message": "Make the headline bolder and increase the contrast on the CTA button",
"target_format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250_generative"
},
"creative_manifest": {
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "display_300x250"
},
"assets": {
"banner_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/generated/banner_12345.png",
"width": 300,
"height": 250
},
"headline": {
"asset_type": "text",
"content": "50% Off Winter Sale"
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://mybrand.example.com/winter-sale?campaign={MEDIA_BUY_ID}"
}
}
}
}
```
## エラーコード
| コード | 説明 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FORMAT_NOT_SUPPORTED` | `target_format_id`（またはマルチフォーマットリクエストの `target_format_ids[N]`）がこのクリエイティブエージェントでサポートされていない。正準的なクリエイティブエージェントルーティングでは、表明された `creative.supported_formats[].capability_id` でリトライしてください。レガシーの名前付きフォーマット ID は、エージェントがまだそれらを表明している場合は有効なままです。 |
| `INVALID_MANIFEST` | `creative_manifest` の形式が不正か、ターゲットフォーマットに必要なアセットが不足している |
| `CREATIVE_NOT_FOUND` | `creative_id` がエージェントのライブラリに存在しない（または指定した `concept_id` 内に存在しない） |
| `COMPLIANCE_UNSATISFIED` | ブリーフからの必須ディスクロージャーをターゲットフォーマットでレンダーできない（例: フォーマットが必要なディスクロージャーポジションをサポートしない） |