/schemas/v3/creative/list-creative-formats-request.json
Response Schema: /schemas/v3/creative/list-creative-formats-response.json
エージェントタイプ別の動作
Creative Protocol を実装するどのエージェントもlist_creative_formats を提供できます。レスポンスはエージェントが担う役割によって異なります。
専用クリエイティブエージェント(例: https://creative.adcontextprotocol.org):
- 自身が保有する 権威あるフォーマット定義 を返す
- クリエイティブの構築とバリデーションのための完全な仕様を提供します
https://agenticadvertising.org/api/training-agent):
- 稼働中のプロダクトで使われているフォーマットのみ を返す
- 権威あるフォーマット仕様についてクリエイティブエージェントを参照します
- 実際に購入可能なものに基づいて結果をフィルタリングします
リクエストパラメーター
複数レンダーの寸法フィルタリング
フォーマットは複数のレンダー(例: 動画 + コンパニオンバナー)を生成する場合があります。寸法フィルターは 「いずれかのレンダーが合致すれば OK」 というロジックです。max_width: 300, max_height: 250- 少なくとも 1 つ のレンダーが 300×250 以下であれば一致- ユースケース: 「300×250 の広告枠に収まるフォーマットを探す」
- 例: メイン動画 (1920×1080) とコンパニオンバナー (300×250) を持つフォーマットは、バナーが収まるため 一致
レスポンス
完全なフォーマット構造は Format schema を参照。
再帰的な探索
クリエイティブエージェントは、追加フォーマットを提供する他のクリエイティブエージェントを参照する場合があります。creative_agents を再帰的に問い合わせできます。無限ループを避けるため、訪問済み URL を必ず追跡すること。
カタログ要件
フォーマットはassets 配列の catalog アセットタイプとしてカタログのニーズを宣言します。これにより、バイヤーはそのフォーマット向けのクリエイティブを送信する前にどのカタログを同期すべきかを把握できます。
asset_type: "catalog" を使用し、以下を含む requirements オブジェクトを持ちます。
カタログアセットが存在する場合、バイヤーはクリエイティブを送信する前に
sync_catalogs で必要なカタログを同期すること。完全なライフサイクルはカタログを参照。
よくあるシナリオ
プロダクトのフォーマット ID から仕様を取得します
アセットタイプでフォーマットを探す
サードパーティタグ対応フォーマットを探す
種別と寸法で絞り込む
名前で検索します
レスポンシブフォーマットを探す
ビルドケイパビリティを探索します
一部のフォーマットはoutput_format_ids 経由で生成できる出力フォーマットを宣言します。マルチパブリッシャーのテンプレートツールのようなクリエイティブビルダーは、1 つのアセットグループを受け取り多くのパブリッシャー固有フォーマットを生成する場合があります。フォーマットトランスフォーマーは既存のクリエイティブを受け取り再フォーマットする場合があります。
フォーマットスキーマはリレーションシップの両側を表現します。
input_format_ids— このフォーマットが入力として受け付ける既存のクリエイティブフォーマットoutput_format_ids— このフォーマットが生成できる具体的な出力フォーマット
asset_types とこれらのフィルターは異なるものを対象にしています。クリエイティブマニフェストのみを入力として受け取るフォーマットは assets 配列にエントリを持たないため、asset_types と input_format_ids を組み合わせると通常は結果が返らない。
配信時のダイナミッククリエイティブ(広告配信時にデータフィードからレンダーする DCO プラットフォーム)はこれらのフィールドでは表現されない。それらのプラットフォームは assets 経由で入力を、フォーマット自体で出力を記述します。
必要な出力フォーマットが決まっている場合、どんな入力が受け付けられるか?
手持ちの入力フォーマットから、どんな出力を生成できるか?
フォーマット構造
各フォーマットには次が含まれます。アセットロール
共通のアセットロールはアセットの用途を把握するのに役立つ。hero_image- メインビジュアルhero_video- メインの動画コンテンツlogo- ブランドロゴheadline- メインテキストbody_text- セカンダリテキストcall_to_action- CTA ボタン文言
アセットタイプのフィルターロジック
asset_types パラメーターは OR ロジック で、指定したいずれかのアセットタイプを受け付けるフォーマットが返されます。
例: asset_types: ['html', 'javascript', 'image']
- html または javascript または image を受け付けるフォーマットが返る
- ユースケース: 「手元のアセットタイプのどれかで使えるフォーマットを知りたい」
test=false
複数レンダーフォーマットの寸法フィルタリング
複数の成果物を生成するフォーマット例:- コンパニオンバナー付き動画 - メイン動画 (1920×1080) + バナー (300×250)
- アダプティブディスプレイ - デスクトップ (728×90) + モバイル (320×50)
- DOOH 設置 - 寸法が異なる複数画面
test=false
実装上の要件
クリエイティブエージェントでlist_creative_formats を実装する場合:
- 権威あるフォーマットを返す - 定義するフォーマットに関する完全な仕様を含めます
- 他エージェントを参照する -
creative_agentsを使って他のクリエイティブエージェントに委譲します - 能力を明記する - validation、assembly、generation、preview などサポートする操作を示します
- フィルターをサポートする - type、asset_types、寸法などのフィルターパラメーターを実装します
エラーハンドリング
ベストプラクティス
1. format_ids パラメーターを使うget_products で返されたフォーマット仕様を取得する最も効率的な方法。
2. フォーマット仕様をキャッシュする
フォーマット仕様は滅多に変わらないため、format_id ごとにキャッシュして API 呼び出しを減らす。
3. タグ系はアセットタイプで検索する
asset_types: ['html'] や ['javascript'] を指定してタグを受け付けるフォーマットを探す。
4. 複数レンダーフォーマットを考慮する
renders 配列の長さを確認し、複数の掲出面が必要かどうかを把握します。
5. アセット要件を検証する
クリエイティブを構築する前に、アセットがフォーマット仕様に一致していることを確認します。
次のステップ
フォーマットを探索したら:- クリエイティブを構築:
build_creativeでアセットをフォーマットに組み立てる - プレビュー:
preview_creativeでビジュアルを確認します - 検証:
sync_creativesにdry_run: trueを指定して検証します - アップロード:
sync_creativesでエージェントホスト型クリエイティブライブラリにアップロードします
参考
- Format Schema - フォーマット構造の全体像
- Asset Types - アセット仕様の詳細
- Standard Formats - IAB 互換のリファレンスフォーマット