Skip to main content
クリエイティブエージェントがサポートするクリエイティブフォーマットを探索します。アセット要件や技術的制約を含む完全なフォーマット仕様を返します。 応答時間: 約 1 秒（データベース参照） 認証: 不要（フォーマット探索のための公開エンドポイント） Request Schema: /schemas/v2/media-buy/list-creative-formats-request.json Response Schema: /schemas/v2/media-buy/list-creative-formats-response.json

​
営業エージェントとクリエイティブエージェントの違い

list_creative_formats は営業エージェントとクリエイティブエージェントの両方が実装しますが、挙動が異なります。 クリエイティブエージェント（例: https://creative.adcontextprotocol.org）:
  • 自身が保有する 権威あるフォーマット定義 を返す
  • 追加フォーマットについて他のクリエイティブエージェントを参照する場合がある
  • クリエイティブ構築と検証のための完全な仕様を提供する
営業エージェント（例: https://test-agent.adcontextprotocol.org）:
  • 稼働中のプロダクトで使われているフォーマットのみ を返す
  • フォーマット仕様についてクリエイティブエージェントを参照する
  • 実際に購入可能なものに基づいて結果をフィルタリングする
営業エージェント固有の挙動は list_creative_formats (Sales Agent) を参照してください。

​
リクエストパラメーター

ParameterTypeRequiredDescription
format_idsFormatID[]No特定のフォーマット ID のみ返す（get_products レスポンス由来）
typestringNo種別でフィルター: audio, video, display, dooh
asset_typesstring[]Noimage, video, audio, text, html, javascript, url を受け付けるフォーマットに絞り込む（OR ロジック）
max_widthintegerNo最大幅（ピクセル、以上は含む）- いずれかのレンダーが収まれば一致
max_heightintegerNo最大高さ（ピクセル、以上は含む）- いずれかのレンダーが収まれば一致
min_widthintegerNo最小幅（ピクセル、以上は含む）
min_heightintegerNo最小高さ（ピクセル、以上は含む）
is_responsivebooleanNoレスポンシブ対応（コンテナサイズに適応）に絞る
name_searchstringNo名前による検索（大文字小文字を区別しない部分一致）

​
複数レンダーの寸法フィルタリング

フォーマットは複数のレンダー（例: 動画 + コンパニオンバナー）を生成する場合があります。寸法フィルターは 「いずれかのレンダーが合致すれば OK」 というロジックです。
  • max_width: 300, max_height: 250 - 少なくとも 1 つ のレンダーが 300×250 以下であれば一致
  • ユースケース: 「300×250 の広告枠に収まるフォーマットを探す」
  • 例: メイン動画 (1920×1080) とコンパニオンバナー (300×250) を持つフォーマットは、バナーが収まるため 一致

​
レスポンス

FieldDescription
formatsフォーマット定義の配列（format_id、name、type、requirements、assets、renders を含む）
creative_agents追加フォーマットを提供する他のクリエイティブエージェントの任意配列
完全なフォーマット構造は Format schema を参照してください。

​
再帰的な探索

クリエイティブエージェントは、追加フォーマットを提供する他のクリエイティブエージェントを参照する場合があります。 
{
  "creative_agents": [{
    "agent_url": "https://creative.adcontextprotocol.org",
    "agent_name": "AdCP Reference Creative Agent",
    "capabilities": ["validation", "assembly", "preview"]
  }]
}
バイヤーは creative_agents を再帰的に問い合わせできます。無限ループを避けるため、訪問済み URL を必ず追跡してください。

​
よくあるシナリオ

​
プロダクトのフォーマット ID から仕様を取得する

import { testAgent } from '@adcp/client/testing';
import { ListCreativeFormatsResponseSchema } from '@adcp/client';

// Get full specs for formats returned by get_products
const result = await testAgent.listCreativeFormats({
  format_ids: [
    {
      agent_url: 'https://creative.adcontextprotocol.org',
      id: 'video_15s_hosted'
    },
    {
      agent_url: 'https://creative.adcontextprotocol.org',
      id: 'display_300x250'
    }
  ]
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

// Validate response against schema
const validated = ListCreativeFormatsResponseSchema.parse(result.data);
validated.formats.forEach(format => {
  console.log(`${format.name}: ${format.assets.length} assets required`);
});

​
アセットタイプでフォーマットを探す

import { testAgent } from '@adcp/client/testing';
import { ListCreativeFormatsResponseSchema } from '@adcp/client';

// Find formats that accept images and text
const result = await testAgent.listCreativeFormats({
  asset_types: ['image', 'text']
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = ListCreativeFormatsResponseSchema.parse(result.data);
console.log(`Found ${validated.formats.length} formats`);

// Examine asset requirements
validated.formats.forEach(format => {
  console.log(`\n${format.name}:`);
  format.assets.forEach(asset => {
    console.log(`  - ${asset.asset_role}: ${asset.asset_type}`);
  });
});

​
サードパーティタグ対応フォーマットを探す

import { testAgent } from '@adcp/client/testing';
import { ListCreativeFormatsResponseSchema } from '@adcp/client';

// Find formats that accept JavaScript or HTML tags
const result = await testAgent.listCreativeFormats({
  asset_types: ['javascript', 'html'],
  max_width: 970,
  max_height: 250
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = ListCreativeFormatsResponseSchema.parse(result.data);
console.log(`Found ${validated.formats.length} third-party tag formats ≤ 970×250`);

validated.formats.forEach(format => {
  const renders = format.renders || [];
  if (renders.length > 0) {
    const dims = renders[0].dimensions;
    console.log(`${format.name}: ${dims.width}×${dims.height}`);
  }
});

​
種別と寸法で絞り込む

import { testAgent } from '@adcp/client/testing';
import { ListCreativeFormatsResponseSchema } from '@adcp/client';

// Find video formats
const result = await testAgent.listCreativeFormats({
  type: 'video'
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = ListCreativeFormatsResponseSchema.parse(result.data);
console.log(`Found ${validated.formats.length} video formats`);

// Group by duration
const byDuration = {};
validated.formats.forEach(format => {
  const duration = format.requirements?.duration || 'unknown';
  if (!byDuration[duration]) byDuration[duration] = [];
  byDuration[duration].push(format.name);
});

Object.entries(byDuration).forEach(([duration, formats]) => {
  console.log(`${duration}s: ${formats.join(', ')}`);
});

​
名前で検索する

import { testAgent } from '@adcp/client/testing';
import { ListCreativeFormatsResponseSchema } from '@adcp/client';

// Find mobile-optimized formats
const result = await testAgent.listCreativeFormats({
  name_search: 'mobile'
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = ListCreativeFormatsResponseSchema.parse(result.data);
console.log(`Found ${validated.formats.length} mobile formats`);

validated.formats.forEach(format => {
  console.log(`- ${format.name} (${format.type})`);
});

​
レスポンシブフォーマットを探す

import { testAgent } from '@adcp/client/testing';
import { ListCreativeFormatsResponseSchema } from '@adcp/client';

// Find formats that adapt to container size
const result = await testAgent.listCreativeFormats({
  is_responsive: true,
  type: 'display'
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = ListCreativeFormatsResponseSchema.parse(result.data);
console.log(`Found ${validated.formats.length} responsive display formats`);

validated.formats.forEach(format => {
  console.log(`${format.name}: Adapts to container`);
});

​
フォーマット構造

各フォーマットには次が含まれます。
FieldDescription
format_idagent_url と id を持つ構造化された識別子
name人が読みやすいフォーマット名
typeフォーマット種別（audio、video、display、dooh）
requirements技術要件（尺、ファイル形式、ビットレートなど）
assetsすべてのアセット配列。必須か任意かは required ブール値で示す
rendersレンダリングされる成果物の配列（寸法、役割）

​
アセットロール

共通のアセットロールはアセットの用途を把握するのに役立ちます。
  • 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
// 画像とテキストの両方を必要とするフォーマットを探す
const result = await agent.listCreativeFormats();
const imageAndText = result.formats.filter(format => {
  const assetTypes = format.assets.map(a => a.asset_type);
  return assetTypes.includes('image') && assetTypes.includes('text');
});

​
複数レンダーフォーマットの寸法フィルタリング

複数の成果物を生成するフォーマット例:
  • コンパニオンバナー付き動画 - メイン動画 (1920×1080) + バナー (300×250)
  • アダプティブディスプレイ - デスクトップ (728×90) + モバイル (320×50)
  • DOOH 設置 - 寸法が異なる複数画面
寸法フィルターは 少なくとも 1 つのレンダー が条件に合えば一致します。
test=false
// いずれかのレンダーが 300×250 以下のフォーマットを探す
const result = await agent.listCreativeFormats({
  max_width: 300,
  max_height: 250
});

// 300×250 の枠に収まるレンダーが 1 つでもあれば返される
// より大きいコンパニオンを含む場合もある

​
実装上の要件

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

​
エラーハンドリング

Error CodeDescriptionResolution
FORMAT_NOT_FOUNDリクエストされた format_id が存在しないget_products のレスポンスから format_id を確認する
INVALID_REQUESTフィルターパラメーターが不正パラメーターの型と値を確認する
AGENT_NOT_FOUND参照先のクリエイティブエージェントが利用不可廃止されたエージェント由来のフォーマットの可能性

​
ベストプラクティス

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_creatives に dry_run: true を指定して検証する
  4. アップロード: sync_creatives でメディアバイにアップロードする

​
参考