AdCP — preview

Generate preview renderings of creative manifests. Supports both single creative preview and batch preview (5-10x faster for multiple creatives). Request Schema: /schemas/3.0.19/creative/preview-creative-request.json Response Schema: /schemas/3.0.19/creative/preview-creative-response.json

Quick Start

Single Creative Preview

{
  "request_type": "single",
  "creative_manifest": { /* includes format_id, assets */ }
}

Response:

{
  "response_type": "single",
  "previews": [
    {
      "preview_id": "prev_001",
      "renders": [
        {
          "render_id": "render_1",
          "output_format": "url",
          "preview_url": "https://creative-agent.example.com/preview/abc123",
          "role": "primary"
        }
      ],
      "input": { "name": "Default", "macros": {} }
    }
  ],
  "expires_at": "2027-02-15T18:00:00Z"
}

Embed the primary render in an iframe:

<iframe src="https://creative-agent.example.com/preview/abc123"
        width="600" height="400"></iframe>

Direct HTML Embedding

For faster rendering without iframe overhead, request HTML directly:

{
  "request_type": "single",
  "creative_manifest": { /* includes format_id, assets */ },
  "output_format": "html"
}

Response contains raw HTML:

{
  "response_type": "single",
  "previews": [
    {
      "preview_id": "prev_002",
      "renders": [
        {
          "render_id": "render_1",
          "output_format": "html",
          "preview_html": "<div class=\"creative\">...</div>",
          "role": "primary"
        }
      ],
      "input": { "name": "Default", "macros": {} }
    }
  ],
  "expires_at": "2027-02-15T18:00:00Z"
}

Only use output_format: "html" with trusted creative agents. Direct HTML embedding bypasses iframe sandboxing.

Batch Preview (Multiple Creatives)

Preview multiple creatives in one API call (5-10x faster):

{
  "request_type": "batch",
  "requests": [
    { "creative_manifest": { /* creative 1 */ } },
    { "creative_manifest": { /* creative 2 */ } }
  ]
}

Response contains results in order:

{
  "response_type": "batch",
  "results": [
    { "success": true, "creative_id": "creative_1", "response": { "previews": [...], "expires_at": "..." } },
    { "success": true, "creative_id": "creative_2", "response": { "previews": [...], "expires_at": "..." } }
  ]
}

Variant Preview (Post-Flight)

Preview what a specific variant looked like when served. Use variant_id from get_creative_delivery response:

{
  "request_type": "variant",
  "variant_id": "gen_mobile_morning"
}

Response:

{
  "response_type": "variant",
  "variant_id": "gen_mobile_morning",
  "previews": [
    {
      "preview_id": "prev_gen_morning",
      "renders": [
        {
          "render_id": "render_1",
          "output_format": "url",
          "preview_url": "https://creative-agent.example.com/preview/variant/gen_mobile_morning",
          "role": "primary",
          "dimensions": { "width": 300, "height": 250 }
        }
      ]
    }
  ],
  "manifest": {
    "format_id": {
      "agent_url": "https://creative.example.com",
      "id": "display_300x250_generative"
    },
    "assets": {
      "hero_image": {
        "asset_type": "image",
        "url": "https://cdn.creative.example.com/generated/mobile_morning_v1.jpg",
        "width": 300,
        "height": 250
      },
      "headline": {
        "asset_type": "text",
        "content": "Start Your Summer Right"
      }
    }
  },
  "expires_at": "2027-02-15T18:00:00Z"
}

Since each variant from get_creative_delivery includes its full manifest, you can also pass the manifest directly to preview_creative as a standard single request to re-render it.

Request Parameters

All modes use a single flat object with request_type as the discriminant.

Parameter	Type	Required	Description
`request_type`	string	Yes	`"single"`, `"batch"`, or `"variant"`
`creative_manifest`	object	Single	Complete creative manifest with all required assets for the format.
`format_id`	FormatID	No	Format identifier (agent_url + id). Defaults to `creative_manifest.format_id` if omitted. Used in single mode.
`inputs`	array	No	Array of input sets for multiple preview variants. Used in single mode.
`quality`	string	No	`"draft"` (fast, lower-fidelity) or `"production"` (full quality). In batch mode, sets the default for all requests.
`output_format`	string	No	`"url"` (default) or `"html"`. In batch mode, sets the default for all requests.
`item_limit`	integer	No	Maximum catalog items to render per preview variant. Used in single mode.
`template_id`	string	No	Specific template ID for custom format rendering. Used in single mode.
`requests`	array	Batch	Array of 1-50 preview requests. Each item accepts `creative_manifest` (required), `format_id`, `inputs`, `quality`, `output_format`, `item_limit`, and `template_id`.
`variant_id`	string	Variant	Platform-assigned variant identifier from `get_creative_delivery`.
`creative_id`	string	No	Creative identifier for context. Used in variant mode.

Required column values: Single = required when request_type is "single", Batch = required when "batch", Variant = required when "variant".

Input Sets

Generate multiple preview variants by providing different contexts:

{
  "inputs": [
    { "name": "Desktop", "macros": { "DEVICE_TYPE": "desktop" } },
    { "name": "Mobile", "macros": { "DEVICE_TYPE": "mobile" } },
    { "name": "Morning Context", "context_description": "User commuting to work" }
  ]
}

Available macros: DEVICE_TYPE, COUNTRY, CITY, DMA, GDPR, US_PRIVACY, CONTENT_GENRE, etc. Context descriptions: For AI-generated content like host-read audio ads.

Response Format

Single Mode Response

{
  response_type: "single";
  previews: Preview[];       // One per input (or one default)
  interactive_url?: string;  // Optional sandbox for interactive formats
  expires_at: string;        // ISO 8601 expiration
}

Batch Mode Response

{
  response_type: "batch";
  results: Array<{
    success: boolean;
    creative_id: string;
    response?: { previews: Preview[]; expires_at: string; };
    errors?: Array<{ code: string; message: string; }>;
  }>;
}

Preview Structure

{
  preview_id: string;
  renders: Array<{
    render_id: string;
    output_format: "url" | "html" | "both";
    preview_url?: string;     // When output_format is "url" or "both"
    preview_html?: string;    // When output_format is "html" or "both"
    role: string;             // "primary", "companion", etc.
    dimensions?: { width: number; height: number; };
  }>;
  input: {
    name: string;
    macros?: Record<string, string>;
    context_description?: string;
  };
}

Multi-render formats: Some formats produce multiple pieces (video + companion banner). Each has its own render_id and role.

Previewing generative creative

For generative formats — contextual display, AI-generated native, conversational ads — the creative doesn’t exist until serve time. Preview serves two distinct purposes:

Pre-flight: representative samples

Before the campaign runs, use single or batch mode to preview what the agent could generate given different contexts. Pass inputs with context_description to simulate serve-time conditions:

{
  "$schema": "/schemas/3.0.19/creative/preview-creative-request.json",
  "request_type": "single",
  "quality": "draft",
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://ads.seller-example.com",
      "id": "contextual_display_generative"
    },
    "assets": {
      "brief": {
        "asset_type": "brief",
        "name": "Sustainability story",
        "objective": "awareness",
        "messaging": {
          "key_messages": ["Highlight our sustainability story. Match tone to editorial context."]
        }
      }
    }
  },
  "inputs": [
    { "name": "Tech article", "context_description": "Article about semiconductor manufacturing" },
    { "name": "Lifestyle blog", "context_description": "Blog post about sustainable living" }
  ]
}

These previews are representative, not definitive. Real serve-time output depends on live signals (actual page content, user device, time of day) that can’t be fully simulated. Use draft quality for fast iteration on the brief and creative direction, then production quality for stakeholder review.

Post-flight: exact replay

After the campaign runs, use variant mode to see exactly what was served. Pass a variant_id from get_creative_delivery:

{
  "request_type": "variant",
  "variant_id": "gen_tech_mobile_001"
}

The response includes the variant’s actual manifest — the specific headline, image, and layout the agent generated for that context. This is a faithful replay, not a re-generation.

Setting expectations

Aspect	Standard creative	Generative creative
Pre-flight preview	Exact — what you see is what runs	Representative — shows the agent’s interpretation of the brief under simulated conditions
Post-flight preview	Same as pre-flight	Exact — faithful replay of served output via variant mode
`quality: "draft"`	Fast wireframe-quality render	Fast, lower-fidelity generation for reviewing creative direction
`quality: "production"`	Full-fidelity render	Full-quality generation for stakeholder sign-off
Number of variants	Typically 1 (or a few device variants)	Potentially thousands — one per context

For generative formats where every impression produces a different creative (like AI chat or real-time contextual), pre-flight previews are best understood as samples from a distribution rather than the ad. The brief and brand identity constrain the distribution; previews let you verify the agent interprets those constraints correctly.

Conversational and interactive formats

For formats where the ad is stateful — AI chat, interactive experiences, conversational native — preview takes on additional meaning:

Pre-flight renders a representative first interaction or simulated conversation. The interactive_url field in the preview response (when present) provides a sandbox where reviewers can interact with the experience directly. Use context_description to simulate different conversation entry points.
Post-flight variant replay shows the actual exchange that occurred. For multi-turn formats, the variant manifest captures the full content the agent produced (message sequence, responses, media assets shown). The level of detail depends on the agent — some provide full transcripts, others provide summarized content with anonymized user signals.

These formats have the widest gap between pre-flight and post-flight: a pre-flight preview can only approximate one possible conversation path, while the live experience adapts to each user. Preview enough scenarios to verify tone, guardrails, and brand consistency.

Quality mismatch

If the requested quality level is not supported, the agent renders at the best quality it can provide. The protocol does not require agents to support both levels — an agent that only generates at one fidelity ignores the parameter. There is no response field echoing back the actual quality used, so if quality accuracy matters for your workflow, verify by visual inspection or ask the agent about its capabilities through list_creative_formats.

Preview expiration and variant retention

All previews have an expires_at timestamp. After expiration, preview URLs return errors and must be re-generated. For generative creative, re-generating a pre-flight preview may produce different output — the same brief and context can yield different creative each time. Variant previews (post-flight) depend on the agent retaining variant data. Agents are not required to retain variant data indefinitely. If you request a variant preview for a variant the agent has purged, expect a standard error response. For long-running campaigns, retrieve and archive variant previews periodically rather than assuming they will remain available.

Examples

Device Variants

{
  "$schema": "/schemas/3.0.19/creative/preview-creative-request.json",
  "request_type": "single",
  "creative_manifest": {
    "format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "native_responsive" },
    "assets": {
      "hero_image": { "asset_type": "image", "url": "https://cdn.example.com/hero.jpg", "width": 1200, "height": 627 },
      "headline": { "asset_type": "text", "content": "Veterinarian Recommended" }
    }
  },
  "inputs": [
    { "name": "Desktop", "macros": { "DEVICE_TYPE": "desktop" } },
    { "name": "Mobile", "macros": { "DEVICE_TYPE": "mobile" } }
  ]
}

Batch with HTML Output

Preview multiple creatives for a grid layout:

{
  "request_type": "batch",
  "output_format": "html",
  "requests": [
    { "creative_manifest": { /* creative 1 */ } },
    { "creative_manifest": { /* creative 2 */ } }
  ]
}

AI-Generated Audio Preview

{
  "$schema": "/schemas/3.0.19/creative/preview-creative-request.json",
  "request_type": "single",
  "creative_manifest": {
    "format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "audio_host_read_30s" },
    "assets": {
      "script_template": { "content": "This episode brought to you by {{BRAND_NAME}}..." },
      "brand_voice": { "content": "Friendly, enthusiastic, conversational." }
    }
  },
  "inputs": [
    { "name": "Weather Podcast", "context_description": "Podcast discussing weather patterns" },
    { "name": "Fitness Podcast", "context_description": "Podcast about marathon training" }
  ]
}

HTTP Status Codes

Single mode:

200 OK - Preview generated successfully
400 Bad Request - Invalid manifest or format_id
404 Not Found - Format not supported

Batch mode:

200 OK - Batch processed (check individual success fields)
400 Bad Request - Invalid batch structure

Key Points

Every render’s preview_url returns an HTML page for iframe embedding
Use output_format: "html" for grids of 10+ previews (no iframe overhead)
Batch mode is 5-10x faster than individual requests
Preview URLs expire (check expires_at)
Handle partial batch failures by checking each result’s success field

Advanced Preview Patterns - Caching, workflows, implementation notes
Creative Manifests - Manifest structure
Creative Formats - Format specifications

​Quick Start

​Single Creative Preview

​Direct HTML Embedding

​Batch Preview (Multiple Creatives)

​Variant Preview (Post-Flight)

​Request Parameters

​Input Sets

​Response Format

​Single Mode Response

​Batch Mode Response

​Preview Structure

​Previewing generative creative

​Pre-flight: representative samples

​Post-flight: exact replay

​Setting expectations

​Conversational and interactive formats

​Quality mismatch

​Preview expiration and variant retention

​Examples

​Device Variants

​Batch with HTML Output

​AI-Generated Audio Preview

​HTTP Status Codes

​Key Points

​Related Documentation

Quick Start

Single Creative Preview

Direct HTML Embedding

Batch Preview (Multiple Creatives)

Variant Preview (Post-Flight)

Request Parameters

Input Sets

Response Format

Single Mode Response

Batch Mode Response

Preview Structure

Previewing generative creative

Pre-flight: representative samples

Post-flight: exact replay

Setting expectations

Conversational and interactive formats

Quality mismatch

Preview expiration and variant retention

Examples

Device Variants

Batch with HTML Output

AI-Generated Audio Preview

HTTP Status Codes

Key Points

Related Documentation