Skip to main content
クリエイティブエージェントがサポートするクリエイティブフォーマットを探索します。アセット要件や技術的制約を含む完全なフォーマット仕様を返します。 応答時間: 約 1 秒(データベース参照) 認証: 不要(フォーマット探索のための公開エンドポイント) Request Schema: /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):
  • 自身が保有する 権威あるフォーマット定義 を返す
  • クリエイティブの構築とバリデーションのための完全な仕様を提供します
Media Buy Protocol のみを実装する営業エージェント(例: https://agenticadvertising.org/api/training-agent):
  • 稼働中のプロダクトで使われているフォーマットのみ を返す
  • 権威あるフォーマット仕様についてクリエイティブエージェントを参照します
  • 実際に購入可能なものに基づいて結果をフィルタリングします
両方のプロトコルを実装する営業エージェント — 自前のフォーマット定義と参照フォーマットを合わせて返します。セールスエージェントのクリエイティブ機能を参照。 営業エージェント固有の挙動は list_creative_formats (Sales 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 — このフォーマットが生成できる具体的な出力フォーマット
これらのフィルターは AND で組み合わされます。フォーマットは指定したすべてのフィルターに一致しなければなりません。各フィルター内でのマッチングは OR(配列内のいずれかの ID が一致)です。ディメンションパラメーターなしの裸のフォーマット ID はそのフォーマットのすべてのパラメーター化されたバリアントに一致し、パラメーター化された ID は完全一致です。 注意: asset_types とこれらのフィルターは異なるものを対象にしています。クリエイティブマニフェストのみを入力として受け取るフォーマットは assets 配列にエントリを持たないため、asset_typesinput_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 設置 - 寸法が異なる複数画面
寸法フィルターは 少なくとも 1 つのレンダー が条件に合えば一致します。
test=false

実装上の要件

クリエイティブエージェントで list_creative_formats を実装する場合:
  1. 権威あるフォーマットを返す - 定義するフォーマットに関する完全な仕様を含めます
  2. 他エージェントを参照する - creative_agents を使って他のクリエイティブエージェントに委譲します
  3. 能力を明記する - validation、assembly、generation、preview などサポートする操作を示します
  4. フィルターをサポートする - type、asset_types、寸法などのフィルターパラメーターを実装します

エラーハンドリング

ベストプラクティス

1. format_ids パラメーターを使う get_products で返されたフォーマット仕様を取得する最も効率的な方法。 2. フォーマット仕様をキャッシュする フォーマット仕様は滅多に変わらないため、format_id ごとにキャッシュして API 呼び出しを減らす。 3. タグ系はアセットタイプで検索する asset_types: ['html']['javascript'] を指定してタグを受け付けるフォーマットを探す。 4. 複数レンダーフォーマットを考慮する renders 配列の長さを確認し、複数の掲出面が必要かどうかを把握します。 5. アセット要件を検証する クリエイティブを構築する前に、アセットがフォーマット仕様に一致していることを確認します。

次のステップ

フォーマットを探索したら:
  1. クリエイティブを構築: build_creative でアセットをフォーマットに組み立てる
  2. プレビュー: preview_creative でビジュアルを確認します
  3. 検証: sync_creativesdry_run: true を指定して検証します
  4. アップロード: sync_creatives でエージェントホスト型クリエイティブライブラリにアップロードします

参考