Skip to main content
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

{
  "request_type": "single",
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "native_responsive"
  },
  "creative_manifest": { /* your creative */ }
}
Response: 
{
  "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: 
<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",
  "format_id": { "agent_url": "...", "id": "native_responsive" },
  "creative_manifest": { /* your creative */ },
  "output_format": "html"
}
Response contains raw HTML: 
{
  "response_type": "single",
  "previews": [
    {
      "preview_html": "<div class=\"creative\">...</div>",
      "input": { "name": "Default", "macros": {} }
    }
  ]
}
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": [
    { "format_id": {...}, "creative_manifest": { /* creative 1 */ } },
    { "format_id": {...}, "creative_manifest": { /* creative 2 */ } }
  ]
}
Response contains results in order: 
{
  "response_type": "batch",
  "results": [
    { "success": true, "response": { "previews": [...], "expires_at": "..." } },
    { "success": true, "response": { "previews": [...], "expires_at": "..." } }
  ]
}

​
Request Parameters

​
Single Mode

ParameterTypeRequiredDescription
request_typestringYes"single"
format_idFormatIDYesFormat identifier (agent_url + id)
creative_manifestobjectYesComplete creative manifest
inputsarrayNoArray of input sets for multiple preview variants
output_formatstringNo"url" (default) or "html"

​
Batch Mode

ParameterTypeRequiredDescription
request_typestringYes"batch"
requestsarrayYesArray of 1-50 preview requests
output_formatstringNoDefault output format for all requests

​
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 testing page
  expires_at: string;        // ISO 8601 expiration
}

​
Batch Mode Response

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

​
Preview Structure

{
  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

{
  "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: 
{
  "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

{
  "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