クリエイティブマニフェストのプレビューを生成します。単体プレビューとバッチプレビューの両方をサポートし、複数クリエイティブでは 5〜10 倍高速にレンダリングできます。
クイックスタート
単体クリエイティブのプレビュー
{
"request_type": "single",
"format_id": {
"agent_url": "https://creative.adcontextprotocol.org",
"id": "native_responsive"
},
"creative_manifest": { /* your creative */ }
}
{
"response_type": "single",
"previews": [
{
"preview_url": "https://creative-agent.example.com/preview/abc123",
"input": { "name": "Default", "macros": {} }
}
],
"expires_at": "2025-02-15T18:00:00Z"
}
<iframe src="https://creative-agent.example.com/preview/abc123"
width="600" height="400"></iframe>
HTML 直接埋め込み
iframe を使わず高速にレンダリングする場合は HTML を直接要求します。
{
"request_type": "single",
"format_id": { "agent_url": "...", "id": "native_responsive" },
"creative_manifest": { /* your creative */ },
"output_format": "html"
}
{
"response_type": "single",
"previews": [
{
"preview_html": "<div class=\"creative\">...</div>",
"input": { "name": "Default", "macros": {} }
}
]
}
output_format: "html" は信頼できるクリエイティブエージェントでのみ使用してください。直接 HTML を埋め込むと iframe サンドボックスを回避します。
バッチプレビュー（複数クリエイティブ）
複数クリエイティブを 1 回の API 呼び出しでプレビューします（5〜10 倍高速）。
{
"request_type": "batch",
"requests": [
{ "format_id": {...}, "creative_manifest": { /* creative 1 */ } },
{ "format_id": {...}, "creative_manifest": { /* creative 2 */ } }
]
}
{
"response_type": "batch",
"results": [
{ "success": true, "response": { "previews": [...], "expires_at": "..." } },
{ "success": true, "response": { "previews": [...], "expires_at": "..." } }
]
}
リクエストパラメータ
単体モード
| Parameter | Type | Required | Description |
|---|
request_type | string | Yes | "single" |
format_id | FormatID | Yes | フォーマット ID（agent_url + id） |
creative_manifest | object | Yes | 完成したクリエイティブマニフェスト |
inputs | array | No | 複数プレビューを作るための入力セット |
output_format | string | No | "url"（デフォルト）または "html" |
バッチモード
| Parameter | Type | Required | Description |
|---|
request_type | string | Yes | "batch" |
requests | array | Yes | 1〜50 件のプレビューレコードの配列 |
output_format | string | No | 全リクエストに適用するデフォルトの出力形式 |
{
"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 など
context_description: ホストリード音声広告など AI 生成コンテンツ向けに文脈を渡すために使用。
レスポンス形式
単体モードのレスポンス
{
response_type: "single";
previews: Preview[]; // 入力ごと、またはデフォルト 1 件
interactive_url?: string; // 省略可: テストページ
expires_at: string; // ISO 8601 の有効期限
}
バッチモードのレスポンス
{
response_type: "batch";
results: Array<{
success: boolean;
response?: { previews: Preview[]; expires_at: string; };
error?: PreviewError;
}>;
}
Preview オブジェクト
type Preview = {
previews: Array<{
preview_url?: string; // iframe 用の URL
preview_html?: string; // 直接埋め込み用 HTML
renders?: Array<{
render_type: "image" | "html";
preview_url?: string;
preview_html?: string;
width?: number;
height?: number;
}>;
input: {
name?: string;
macros?: Record<string, string>;
context_description?: string;
};
}>;
expires_at: string;
};
type PreviewError = {
code: string;
message: string;
field?: string;
};
出力形式の選択
output_format: "url"（デフォルト）: 安全性重視、サンドボックスされた iframe での検証に適するoutput_format: "html": フォーマットカタログや大規模なプレビュー一覧を高速表示する場合。信頼できるクリエイティブエージェントでのみ使用
レイテンシとスループット
- 単体リクエスト: 1 件あたりおおむね 200–500ms
- バッチリクエスト: 1〜50 件をまとめて処理し 5–10 倍高速
expires_at まで結果をキャッシュし、同じマニフェスト + format_id では再生成を避ける
エラーハンドリング
バッチモードでは成功と失敗が混在します。results をフィルタリングして失敗のみ再試行するパターンが推奨です。
const response = await client.preview_creative({
request_type: "batch",
requests: formatRequests
});
const failed = response.results.filter(r => !r.success);
if (failed.length > 0) {
failed.forEach((r) => {
console.error(`${r.error.code}: ${r.error.message}`);
});
}
典型的なエラーコード
VALIDATION_ERROR: マニフェストの必須フィールド不足UNSUPPORTED_FORMAT: format_id が無効、またはエージェントが未対応RATE_LIMITED: リクエストが許容量を超過INTERNAL_ERROR: 予期しないサーバーエラー。時間をおいて再試行
よくある利用パターン
- フォーマットギャラリー:
output_format: "html" で 10+ フォーマットを一覧表示
- キャンペーンレビュー: バッチでキャンペーン内のクリエイティブをまとめて確認
- 開発テスト: 単体モードで 1 つのマニフェストを高速に検証
関連ドキュメント
