> ## Documentation Index
> Fetch the complete documentation index at: https://agenticadvertisingorg-snap-format-preview-links.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# preview_creative

Generate preview renderings of creative manifests. Supports both single creative preview and batch preview (5-10x faster for multiple creatives).

## Quick Start

### Single Creative Preview

```json theme={null}
{
  "request_type": "single",
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "native_responsive"
  },
  "creative_manifest": { /* your creative */ }
}
```

Response:

```json theme={null}
{
  "response_type": "single",
  "previews": [
    {
      "preview_url": "https://creative-agent.example.com/preview/abc123",
      "input": { "name": "Default", "macros": {} }
    }
  ],
  "expires_at": "2025-02-15T18:00:00Z"
}
```

Embed in an iframe:

```html theme={null}
<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:

```json theme={null}
{
  "request_type": "single",
  "format_id": { "agent_url": "...", "id": "native_responsive" },
  "creative_manifest": { /* your creative */ },
  "output_format": "html"
}
```

Response contains raw HTML:

```json theme={null}
{
  "response_type": "single",
  "previews": [
    {
      "preview_html": "<div class=\"creative\">...</div>",
      "input": { "name": "Default", "macros": {} }
    }
  ]
}
```

<Warning>
  Only use `output_format: "html"` with trusted creative agents. Direct HTML embedding bypasses iframe sandboxing.
</Warning>

### Batch Preview (Multiple Creatives)

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

```json theme={null}
{
  "request_type": "batch",
  "requests": [
    { "format_id": {...}, "creative_manifest": { /* creative 1 */ } },
    { "format_id": {...}, "creative_manifest": { /* creative 2 */ } }
  ]
}
```

Response contains results in order:

```json theme={null}
{
  "response_type": "batch",
  "results": [
    { "success": true, "response": { "previews": [...], "expires_at": "..." } },
    { "success": true, "response": { "previews": [...], "expires_at": "..." } }
  ]
}
```

## Request Parameters

### Single Mode

| Parameter           | Type     | Required | Description                                       |
| ------------------- | -------- | -------- | ------------------------------------------------- |
| `request_type`      | string   | Yes      | `"single"`                                        |
| `format_id`         | FormatID | Yes      | Format identifier (agent\_url + id)               |
| `creative_manifest` | object   | Yes      | Complete creative manifest                        |
| `inputs`            | array    | No       | Array of input sets for multiple preview variants |
| `output_format`     | string   | No       | `"url"` (default) or `"html"`                     |

### Batch Mode

| Parameter       | Type   | Required | Description                            |
| --------------- | ------ | -------- | -------------------------------------- |
| `request_type`  | string | Yes      | `"batch"`                              |
| `requests`      | array  | Yes      | Array of 1-50 preview requests         |
| `output_format` | string | No       | Default output format for all requests |

### 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";
  previews: Preview[];       // One per input (or one default)
  interactive_url?: string;  // Optional testing page
  expires_at: string;        // ISO 8601 expiration
}
```

### Batch Mode Response

```typescript theme={null}
{
  response_type: "batch";
  results: Array<{
    success: boolean;
    response?: { previews: Preview[]; expires_at: string; };
    error?: { code: string; message: string; };
  }>;
}
```

### Preview Structure

```typescript theme={null}
{
  preview_id: string;
  renders: [{
    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?: object;
    context_description?: string;
  };
}
```

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

## Examples

### Device Variants

```json theme={null}
{
  "request_type": "single",
  "format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "native_responsive" },
  "creative_manifest": {
    "format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "native_responsive" },
    "assets": {
      "hero_image": { "url": "https://cdn.example.com/hero.jpg", "width": 1200, "height": 627 },
      "headline": { "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": [
    {
      "format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "display_300x250" },
      "creative_manifest": { /* creative 1 */ }
    },
    {
      "format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "display_728x90" },
      "creative_manifest": { /* creative 2 */ }
    }
  ]
}
```

### AI-Generated Audio Preview

```json theme={null}
{
  "request_type": "single",
  "format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "audio_host_read_30s" },
  "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 `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

## Related Documentation

* [Advanced Preview Patterns](/dist/docs/2.5.3/creative/task-reference/preview_creative-advanced) - Caching, workflows, implementation notes
* [Creative Manifests](/dist/docs/2.5.3/creative/creative-manifests) - Manifest structure
* [Creative Formats](/dist/docs/2.5.3/creative/formats) - Format specifications