> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adcontextprotocol.org/llms.txt
> Use this file to discover all available pages before exploring further.
# preview_creative
> preview_creative renders an existing creative manifest into viewable output in AdCP, in single or batch mode, returning URL, image, or HTML output.
`preview_creative` renders an existing creative manifest into viewable output. It does not generate or modify the input manifest — use [`build_creative`](/dist/docs/3.2.0-beta.0/creative/task-reference/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`](https://adcontextprotocol.org/schemas/3.2.0-beta.0/creative/preview-creative-request.json)
**Response Schema**: [`/schemas/3.2.0-beta.0/creative/preview-creative-response.json`](https://adcontextprotocol.org/schemas/3.2.0-beta.0/creative/preview-creative-response.json)
## Quick Start
### Single Creative Preview
```json theme={null}
{
"request_type": "single",
"target_capability_id": "preview_image_300x250",
"creative_manifest": { /* includes format_kind, assets */ }
}
```
Response:
```json theme={null}
{
"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:
```html theme={null}
```
### Direct HTML Embedding
For faster rendering without iframe overhead, request HTML directly:
```json theme={null}
{
"request_type": "single",
"target_capability_id": "preview_image_300x250",
"creative_manifest": { /* includes format_kind, assets */ },
"output_format": "html"
}
```
Response contains raw HTML:
```json theme={null}
{
"response_type": "single",
"previews": [
{
"preview_id": "prev_002",
"renders": [
{
"render_id": "render_1",
"output_format": "html",
"preview_html": "...
",
"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):
```json theme={null}
{
"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:
```json theme={null}
{
"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`](/dist/docs/3.2.0-beta.0/creative/task-reference/get_creative_delivery) response:
```json theme={null}
{
"request_type": "variant",
"variant_id": "gen_mobile_morning"
}
```
Response:
```json theme={null}
{
"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`](/dist/docs/3.2.0-beta.0/building/verification/compliance-catalog#error-code-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`](/dist/docs/3.2.0-beta.0/creative/task-reference/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:
```json theme={null}
{
"response_type": "submitted",
"status": "submitted",
"task_id": "task_preview_abc123",
"message": "Production-quality video preview queued"
}
```
The buyer polls [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.0-beta.0/protocol/get-task-status-request.json) 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`](/dist/docs/3.2.0-beta.0/creative/task-reference/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:
```json theme={null}
{
"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
```typescript theme={null}
{
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
```typescript theme={null}
{
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
```typescript theme={null}
{
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;
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:
```json theme={null}
{
"$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`](/dist/docs/3.2.0-beta.0/creative/task-reference/get_creative_delivery):
```json theme={null}
{
"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`](/dist/docs/3.2.0-beta.0/creative/task-reference/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
```json theme={null}
{
"$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:
```json theme={null}
{
"request_type": "batch",
"output_format": "html",
"requests": [
{ "creative_manifest": { /* creative 1 */ } },
{ "creative_manifest": { /* creative 2 */ } }
]
}
```
### AI-Generated Audio Preview
```json theme={null}
{
"$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
## Related Documentation
* [Advanced Preview Patterns](/dist/docs/3.2.0-beta.0/creative/task-reference/preview_creative-advanced) - Caching, workflows, implementation notes
* [Creative Manifests](/dist/docs/3.2.0-beta.0/creative/creative-manifests) - Manifest structure
* [Creative Formats](/dist/docs/3.2.0-beta.0/creative/formats) - Format specifications