AdCP — preview

preview_creative renders an existing creative manifest into viewable output. It does not generate or modify the input manifest — use build_creative for that. Supports both single creative preview and batch preview (5-10x faster for multiple creatives). Request Schema: /schemas/3.2.0-beta.0/creative/preview-creative-request.json Response Schema: /schemas/3.2.0-beta.0/creative/preview-creative-response.json

Quick Start

Single Creative Preview

{
  "request_type": "single",
  "target_capability_id": "preview_image_300x250",
  "creative_manifest": { /* includes format_kind, 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",
  "target_capability_id": "preview_image_300x250",
  "creative_manifest": { /* includes format_kind, 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": [
    { "target_capability_id": "preview_image_300x250", "creative_manifest": { /* creative 1 */ } },
    { "target_capability_id": "preview_video_16x9", "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_kind": "image",
    "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	Conditional	Complete creative manifest with all required assets for the format. For single requests and batch items, supply either this field or `creative_id`.
`creative_manifest.format_kind`	CanonicalFormatKind	Yes for inline manifests	Portable canonical format identity.
`target_capability_id`	string	No	Agent-local renderer route from `get_adcp_capabilities.creative.supported_formats[]`; the selected entry’s `operations` must contain `preview`. In batch mode this is the default for items, which may override it. Omit only when exactly one advertised preview capability matches the canonical manifest; zero or multiple matches return `FORMAT_NOT_SUPPORTED`.
`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 supplies either a canonical `creative_manifest` or library `creative_id`, and may also carry `target_capability_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	Conditional	Creative-library identifier. Use instead of `creative_manifest` to preview a stored canonical creative; in batch mode it is set per item. It may also provide creative context in variant mode.
`allow_async`	boolean	No	Opt in to a `status: "submitted"` response for slow rendering. Defaults to `false`; agents MUST stay synchronous or return a terminal error when absent or false.
`push_notification_config`	object	No	Optional terminal completion/failure webhook when `allow_async` is true and the agent returns `submitted`. The task remains pollable without it; this field alone never causes async execution.

Required column values: Conditional = single requests and batch items require one of creative_manifest or creative_id; Batch = required when request_type is "batch"; Variant = required when "variant". Discover renderers from get_adcp_capabilities.creative.supported_formats[] by selecting entries whose operations contains preview and whose canonical format satisfies the manifest. capability_id is an agent-local renderer route; it never belongs in the portable manifest. If multiple renderers match, the caller must select one explicitly.

Opt-in asynchronous preview

preview_creative is synchronous by default. A buyer that can poll task results MAY set allow_async: true. Only then may an agent hand rendering to a queue or external renderer, release the request connection, and return:

{
  "response_type": "submitted",
  "status": "submitted",
  "task_id": "task_preview_abc123",
  "message": "Production-quality video preview queued"
}

The buyer polls get_task_status with task_id; the completed task result contains the normal single, batch, or variant preview response. If the request also supplies push_notification_config, the agent sends at least the terminal completion/failure notification and the same task remains pollable. response_type: "submitted" keeps this fourth arm in the same discriminator family as the three synchronous preview arms; status: "submitted" is the task-lifecycle signal. submitted is for work that continues after the request connection is released, including a queued upstream renderer. If the agent is actively rendering while keeping the connection open, it uses working progress and returns the normal response on that connection. When allow_async is false or absent, agents MUST NOT return the submitted shape. build_creative already has a separate async response contract and is unchanged by this field. Preview remains read-only in every lifecycle state. Queuing a preview MUST NOT build or approve a creative, add it to a creative library, or modify the supplied or stored manifest.

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";
  quality_used?: "draft" | "production"; // Required when the request supplied quality
  previews: Preview[];       // One per input (or one default)
  interactive_url?: string;  // Optional sandbox for interactive formats
  expires_at?: string;       // Optional ISO 8601 expiration; omitted means no expiration
}

Batch Mode Response

{
  response_type: "batch";
  results: Array<{
    success: boolean;
    creative_id: string;
    quality_used?: "draft" | "production"; // Required when effective request supplied quality
    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.2.0-beta.0/creative/preview-creative-request.json",
  "request_type": "single",
  "quality": "draft",
  "creative_manifest": {
    "format_kind": "agent_placement",
    "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	At production quality, fidelity-accurate within the selected renderer’s presentation; draft may approximate	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"`	Iteration render; final fidelity is not guaranteed	Lower-fidelity sample for reviewing creative direction
`quality: "production"`	Fidelity-accurate review render	Fidelity-accurate sample of serve-time presentation
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 levels

The preview quality tier describes render fidelity, not merely the renderer’s relative cost or speed. It is not a validation result, compliance or brand-safety clearance, seller acceptance, or authorization to serve. Buyers use the applicable validation, governance, and seller creative-review workflows for those decisions.

draft is an iteration render for reviewing creative direction. It MUST preserve the supplied manifest or brief’s core concept, content, and non-fidelity constraints, but it MAY use lower-resolution or placeholder assets; approximate layout, typography, color, motion, audio, or interactive behavior; and omit final polish. The protocol does not guarantee that any of those listed fidelity dimensions is final in a draft preview.
production is a fidelity-accurate review render. For standard or otherwise deterministic creative, it MUST faithfully render the supplied manifest—or the stored manifest resolved from creative_id—and its assets using the serve-time presentation controlled by the selected renderer. In preview_creative, material asset substitution or approximation requires quality_used: "draft". It MUST include disclosure and compliance elements required by the manifest and those owned by that rendering layer for the supplied context.

Publisher- or serving-layer elements outside the selected renderer are guaranteed only when the targeted preview capability represents that integrated rendering context. A standalone creative renderer is not responsible for reproducing downstream elements it cannot determine. Buyers that need an end-to-end composed review SHOULD request a preview from the applicable seller or publisher rendering capability. For generative creative, production means that the sample uses the serve-equivalent generation pipeline and configuration, honors the same declared constraints, and uses the same full-fidelity presentation rules as serve-time generation. It does not promise that the same content will be generated for every impression. Final assets and layout MAY vary where the format varies them at serve time. For stateful or interactive creative, a production preview MUST render the sampled state or path with serve-time visual and control fidelity. The tier makes no behavioral-coverage guarantee beyond that sample. Buyers assessing guardrails, disclosure persistence, error states, or multi-turn behavior SHOULD use interactive_url, when present, and exercise a scenario suite appropriate to the format. These definitions also apply to preview_quality on an inline build_creative preview. In 3.x, that inline response does not echo quality_used, so an agent MUST either meet the requested preview_quality or return preview_error; it cannot silently substitute another tier. Buyers that need a successful response to echo the rendered tier use preview_creative.

Quality mismatch

If the requested quality level is not supported, the agent renders at the best quality it can provide and reports that tier in quality_used. When a single request supplies quality, the response MUST include quality_used. For batch mode, each successful result whose effective request supplied quality—either on the item or through the batch-level default—MUST include quality_used. Agents SHOULD report quality_used even when the request omitted quality, so buyers can record the renderer’s default tier. Buyers MUST compare quality_used with the requested value before treating a preview as a production-fidelity review artifact. A mismatch means the agent applied a different tier; specifically, requested production with quality_used: "draft" is an explicit downgrade. quality_used does not appear on variant-mode replay because that mode reproduces a historical execution rather than selecting a new render-quality tier. Agents are not required to support both quality levels or advertise per-capability quality discovery. In 3.x, quality_used is a binary fidelity gate: it does not identify which dimensions caused a downgrade. Buyers that receive a mismatch need agent-specific or out-of-band diagnostics before deciding whether to retry, select another renderer, or revise the creative.

Preview expiration and variant retention

Preview responses may include an expires_at timestamp. When present, consumers should treat preview URLs as invalid after that time and re-generate them before reuse. When expires_at is omitted, the preview URLs do not expire. For generative creative, re-generating a pre-flight preview may produce different output — the same brief and context can yield different creative each time.

Preview URL durability

preview_url is the protocol resource buyers and MCPUI hosts render. AdCP does not define a separate durable asset pointer for preview renders in 3.x; if a creative agent needs an internal asset key, resource URI, or storage object ID, it remains agent-internal unless the schema adds a future field for it. Creative agents MUST keep each preview_url dereferenceable until the response’s expires_at timestamp. When expires_at is omitted, the URL has no protocol-level expiration and must remain dereferenceable until the agent explicitly revokes or purges it out of band. Do not back preview URLs only with pod-local Map/LRU state in multi-process or multi-pod deployments, because a browser fetch, later refinement call, or reviewer session may land on a different process than the one that created the preview. Durable storage does not require permanent public CDN hosting. A preview URL can resolve through the creative agent’s authenticated preview route as long as the route can recover the render from shared storage, such as a database row, object store key, or shared cache tier, for the advertised lifetime. 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.2.0-beta.0/creative/preview-creative-request.json",
  "request_type": "single",
  "creative_manifest": {
    "format_kind": "native_in_feed",
    "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.2.0-beta.0/creative/preview-creative-request.json",
  "request_type": "single",
  "creative_manifest": {
    "format_kind": "audio_hosted",
    "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 canonical manifest
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 only when expires_at is present; omitted expires_at means no protocol-level expiration
Back preview URLs with storage that survives the URL’s advertised lifetime; process-local maps are only appropriate for single-process demos or shorter-than-process-lifetime URLs
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

Getting Started

Building with AdCP

Protocol

Using AAO

FAQ

Trust & Security

Reference

Certification

preview_creative

Quick Start

Single Creative Preview

Direct HTML Embedding

Batch Preview (Multiple Creatives)

Variant Preview (Post-Flight)

Request Parameters

Opt-in asynchronous preview

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 levels

Quality mismatch

Preview expiration and variant retention

Preview URL durability

Examples

Device Variants

Batch with HTML Output

AI-Generated Audio Preview

HTTP Status Codes

Key Points

​Quick Start

​Single Creative Preview

​Direct HTML Embedding

​Batch Preview (Multiple Creatives)

​Variant Preview (Post-Flight)

​Request Parameters

​Opt-in asynchronous preview

​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 levels

​Quality mismatch

​Preview expiration and variant retention

​Preview URL durability

​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

Opt-in asynchronous preview

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 levels

Quality mismatch

Preview expiration and variant retention

Preview URL durability

Examples

Device Variants

Batch with HTML Output

AI-Generated Audio Preview

HTTP Status Codes

Key Points

Related Documentation