AdCP — Creative Formats

Creative formats define the structural and technical requirements used to instantiate advertising creatives. A format specifies:

The asset types required (video, image, text, audio, etc.) via the assets array
Technical constraints for each asset (duration, dimensions, file types, limits)
How the resulting creative is delivered and validated

Formats define requirements and constraints, not brand content or layout logic. For an overview of how formats, manifests, and creative agents work together, see the Creative Protocol Overview.

Standard vs Custom Formats

AdCP supports two categories of formats based on authority and reuse, not capability.

Standard Formats

Standard formats are predefined specifications provided by the AdCP Reference Creative Agent (https://creative.adcontextprotocol.org). Standard formats are:

Industry-aligned: Based on IAB format families and widely adopted conventions
Portable: Designed to work consistently across platforms
Validated: Pre-tested against known technical constraints
Discoverable: Returned via list_creative_formats
Maintained: Centrally documented and updated

Standard formats typically cover common use cases such as:

Display formats with fixed or responsive dimensions
Video formats with standard durations and aspect ratios
Audio formats with defined spot lengths
Common DOOH display and video executions

Guidance for sales agents: Before defining custom formats, check whether an equivalent standard format already exists. Most publishers can reference standard formats for common inventory and reserve custom formats for genuinely differentiated offerings. See Implementing Standard Format Support for detailed guidance.

Custom Formats

Custom formats are defined by publishers or platforms for inventory that cannot be accurately represented by standard formats. Custom formats may be used when there are:

Unique constraints: Non-standard dimensions, physical displays, or asset requirements
Specialized capabilities: Platform-specific rendering or interaction support
Premium inventory: Differentiated or bespoke ad products
Custom validation logic: Publisher-specific review or assembly rules

Custom formats should be introduced only when necessary. Where possible, standard formats should be reused to maximize portability and buyer understanding.

Discovering Formats

Buyers discover supported formats using the list_creative_formats task exposed by sales agents. Formats may be sourced from:

The sales agent itself - for custom formats
Referenced creative agents - such as the AdCP reference agent, for standard formats

Example discovery response:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/creative/list-creative-formats-response.json",
  "formats": [
    {
      "format_id": {
        "agent_url": "https://youragent.com",
        "id": "homepage_takeover_2024"
      },
      "name": "Homepage Takeover",
      "type": "rich_media"
    }
  ],
  "creative_agents": [
    {
      "agent_url": "https://creative.adcontextprotocol.org"
    }
  ]
}

This indicates that the sales agent supports its own custom format and all formats defined by the referenced creative agent. For sales agents implementing format support: See Implementing Standard Format Support.

Format Authority

Each format includes an agent_url that identifies the authoritative creative agent responsible for the format:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/core/format.json",
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "video_30s_hosted"
  },
  "name": "Standard 30-Second Video"
}

The authoritative creative agent provides:

Complete format specifications
Creative element requirements and constraints
Validation rules
Preview generation
Canonical documentation

Buyers and sales agents rely on the agent_url to retrieve definitive format information.

Format Visual Presentation

Formats may optionally include metadata to support visual browsing and selection in user interfaces.

Example Showcase

Field: example_url Purpose: Deep link to a publisher-controlled showcase May include:

Interactive demos
Videos
Multiple creative examples
Best practices and specifications

This approach allows publishers to present complex formats without constraining presentation in the protocol. Example:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/core/format.json",
  "format_id": {
    "agent_url": "https://publisher.com",
    "id": "homepage_takeover_premium"
  },
  "name": "Premium Homepage Takeover",
  "type": "rich_media",
  "description": "Full-screen immersive experience with video, carousel, and companion units",
  "example_url": "https://publisher.com/formats/homepage-takeover-demo"
}

Referencing Formats

AdCP uses structured format identifiers everywhere to avoid ambiguity and namespace collisions.

Structured Format IDs (Required Everywhere)

ALL format references use structured format ID objects:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/core/format-id.json",
  "agent_url": "https://creative.adcontextprotocol.org",
  "id": "display_300x250"
}

This approach ensures:

Explicit namespacing
Collision-safe identifiers
Schema validation
Extensibility without breaking changes

String-based format identifiers MUST NOT be used in API contracts.

Where Structured Format IDs Are Used

Requests:

sync_creatives - Uploading creative assets
build_creative - Generating creatives via agents implementing the Creative Protocol
preview_creative - Preview generation
create_media_buy - When specifying format requirements

Responses:

list_creatives - Returning creative details
get_products - Product format capabilities
list_creative_formats - Format definitions
Any response containing creative or format details

Filter parameters:

format_ids (plural) in request filters - Array of structured format_id objects

Validation Rules

All AdCP agents MUST:

✅ Accept structured format_id objects in ALL contexts
✅ Return structured format_id objects in ALL responses
❌ Reject string format_ids with clear error messages
❌ Never use string format_ids in any API contract

Error handling for invalid format_id:

{
  "error": "invalid_format_id",
  "message": "format_id must be a structured object with 'agent_url' and 'id' fields",
  "received": "display_300x250",
  "required_structure": {
    "agent_url": "https://creative-agent-url.com",
    "id": "display_300x250"
  }
}

Legacy Considerations

Some legacy systems may send string format_ids. Implementers have two options:

Strict validation (recommended): Reject strings immediately with clear error
Auto-upgrade with deprecation: Accept strings temporarily, log warnings, set removal timeline

If auto-upgrading, you MUST:

Only accept strings for well-known formats you can map to agent URLs
Fail loudly for unknown format strings
Log deprecation warnings on every request
Set and communicate a removal date (recommend 6 months maximum)

Format Structure

Formats are JSON objects with the following key fields:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/core/format.json",
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "video_30s_hosted"
  },
  "name": "30-Second Hosted Video",
  "type": "video",
  "assets": [
    {
      "item_type": "individual",
      "asset_id": "video_file",
      "asset_type": "video",
      "asset_role": "hero_video",
      "required": true,
      "requirements": {
        "duration": "30s",
        "format": ["MP4"],
        "resolution": ["1920x1080", "1280x720"]
      }
    },
    {
      "item_type": "individual",
      "asset_id": "end_card_image",
      "asset_type": "image",
      "asset_role": "end_card",
      "required": false,
      "requirements": {
        "dimensions": "1920x1080",
        "format": ["PNG", "JPG"]
      }
    },
    {
      "item_type": "individual",
      "asset_id": "companion_banner",
      "asset_type": "image",
      "asset_role": "companion",
      "required": false,
      "requirements": {
        "dimensions": "300x250",
        "format": ["PNG", "JPG", "GIF"]
      }
    },
    {
      "item_type": "individual",
      "asset_id": "impression_tracker",
      "asset_type": "url",
      "asset_role": "third_party_tracking",
      "required": false,
      "requirements": {
        "description": "Third-party impression tracking pixel URL"
      }
    }
  ],

  // DEPRECATED: Use "assets" above instead. Kept for backward compatibility.
  "assets": [
    {
      "item_type": "individual",
      "asset_id": "video_file",
      "asset_type": "video",
      "asset_role": "hero_video",
      "requirements": {
        "duration": "30s",
        "format": ["MP4"],
        "resolution": ["1920x1080", "1280x720"]
      }
    }
  ]
}

Key fields:

format_id: Unique identifier (may be namespaced with domain:id)
agent_url: The creative agent authoritative for this format
type: (deprecated, optional) High-level category hint. See note below.
assets: Array of all asset specifications with required boolean indicating mandatory vs optional. This is the authoritative source for understanding creative requirements.
asset_role: Identifies asset purpose (hero_image, logo, cta_button, etc.)
renders: Array of rendered outputs with dimensions - see below
accessibility: Optional WCAG conformance declaration — see Accessibility

Deprecation Notice: The type field is deprecated and optional. The assets array provides precise information about creative requirements (video, image, text, etc.) and should be used instead. Categories like “video”, “display”, and “native” are lossy abstractions that don’t scale well to emerging formats like Performance Max (spans multiple channels), search ads (text-only with high intent), or conversational AI placements.

Asset Discovery

The assets array enables comprehensive asset discovery. Each asset has a required boolean:

required: true - Asset MUST be provided for a valid creative
required: false - Asset is optional, enhances the creative when provided (e.g., companion banners, third-party tracking pixels)

This unified approach helps creative tools and AI agents understand the full capabilities of a format, enabling richer creative experiences when optional assets are available while clearly indicating minimum requirements.

Typed Asset Requirements

Each asset type has its own requirements schema that defines what constraints apply to that asset. The requirements object is typed based on the asset_type: Image assets (asset_type: "image"):

min_width, max_width, min_height, max_height - Dimension constraints (set min=max for exact)
aspect_ratio - Required aspect ratio (e.g., ‘1:1’)
formats - Accepted file formats (jpg, jpeg, png, webp, gif, svg, avif)
max_file_size_kb - Maximum file size
animation_allowed - Whether animated images are accepted
max_animation_duration_ms - Maximum animation duration

Video assets (asset_type: "video"):

min_width, max_width, min_height, max_height - Dimension constraints
aspect_ratio - Required aspect ratio (e.g., ‘16:9’)
min_duration_ms, max_duration_ms - Duration constraints
containers - Accepted container formats (mp4, webm, mov)
codecs - Accepted codecs (h264, h265, vp9, av1)
frame_rates - Accepted frame rates (e.g., [24, 30, 60])
max_file_size_kb, max_bitrate_kbps - Size constraints

HTML assets (asset_type: "html"):

max_file_size_kb - Maximum file size
sandbox - Execution environment (none, iframe, safeframe, fencedframe)
external_resources_allowed - Whether external scripts/images can be loaded
allowed_external_domains - Permitted domains for external resources

JavaScript assets (asset_type: "javascript"):

max_file_size_kb - Maximum file size
module_type - Module format (script, module, iife)
external_resources_allowed - Whether dynamic resource loading is allowed
allowed_external_domains - Permitted domains for dynamic loading

Audio assets (asset_type: "audio"):

min_duration_ms, max_duration_ms - Duration constraints
formats - Accepted audio formats (mp3, aac, wav, ogg, flac)
sample_rates - Accepted sample rates in Hz (e.g., [44100, 48000])
channels - Accepted channel configurations (mono, stereo)
min_bitrate_kbps, max_bitrate_kbps - Bitrate constraints
max_file_size_kb - Maximum file size

Text assets (asset_type: "text"):

min_length, max_length - Character limits
min_lines, max_lines - Line count limits
character_pattern - Regex for allowed characters
prohibited_terms - Words/phrases not allowed

URL assets (asset_type: "url"):

role - Standard purpose (clickthrough, impression_tracker, click_tracker, etc.)
protocols - Allowed protocols (https, http)
allowed_domains - Permitted destination domains
macro_support - Whether macro substitution is supported

Example with HTML execution context:

{
  "asset_id": "banner_html",
  "asset_type": "html",
  "required": true,
  "requirements": {
    "max_file_size_kb": 150,
    "sandbox": "safeframe",
    "external_resources_allowed": false
  }
}

This tells creative agents: “Build HTML that works in a SafeFrame container with no external resource loading.” See Display Ads - HTML Display Formats for complete examples.

Asset Overlays

Some formats include publisher-controlled elements that render on top of buyer creative content — video player controls, publisher logos, and similar chrome. Formats declare these as overlays on the relevant asset so creative agents and buyers know which areas will be covered and can compose accordingly. Overlay bounds are expressed relative to the asset’s own top-left corner. The unit field is either "px" (absolute pixels) or "fraction" (proportional to asset dimensions: for x/y, 0.0 is the asset’s own edge; for width/height, 0.12 means 12% of the asset dimension). Different overlays on the same asset may use different units — creative agents must handle each independently.

{
  "item_type": "individual",
  "asset_id": "video",
  "asset_type": "video",
  "required": true,
  "requirements": {
    "aspect_ratio": "16:9",
    "max_duration_ms": 15000
  },
  "overlays": [
    {
      "id": "play_pause",
      "description": "Play/pause control — avoid placing CTA, copy, or logos here",
      "bounds": { "x": 0, "y": 285, "width": 120, "height": 120, "unit": "px" },
      "visual": {
        "url": "https://publisher.example.com/controls/play.svg"
      }
    },
    {
      "id": "volume",
      "description": "Volume control",
      "bounds": { "x": 0.88, "y": 0.85, "width": 0.12, "height": 0.15, "unit": "fraction" },
      "visual": {
        "light": "https://publisher.example.com/controls/volume-light.svg",
        "dark": "https://publisher.example.com/controls/volume-dark.svg"
      }
    }
  ]
}

The visual field is optional but strongly recommended — it allows creative agents to composite accurate previews showing buyer content with publisher chrome in place. Use url for a theme-neutral graphic (e.g., an SVG using currentColor), or provide light/dark variants for separate theme-specific assets.

Rendered Outputs and Dimensions

Formats describe one or more rendered outputs, each with defined dimensions and semantic roles. This supports:

Single-render formats
Companion creatives
Multi-placement outputs
Responsive behavior
Physical dimensions for non-personal environments

Formats specify their rendered outputs via the renders array. Most formats produce a single render, but some (companion ads, adaptive formats, multi-placement) produce multiple renders:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/core/format.json",
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_300x250"
  },
  "name": "Display Banner 300x250",
  "type": "display",
  "renders": [
    {
      "role": "primary",
      "dimensions": {
        "width": 300,
        "height": 250,
        "responsive": {
          "width": false,
          "height": false
        }
      }
    }
  ]
}

Multi-render example (companion ad):

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/core/format.json",
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "video_with_companion_300x250"
  },
  "name": "Video with Companion Banner",
  "type": "video",
  "renders": [
    {
      "role": "primary",
      "dimensions": {
        "width": 1920,
        "height": 1080,
        "responsive": {
          "width": false,
          "height": false
        }
      }
    },
    {
      "role": "companion",
      "dimensions": {
        "width": 300,
        "height": 250,
        "responsive": {
          "width": false,
          "height": false
        }
      }
    }
  ]
}

Dimension types: Fixed dimensions (standard display ads):

{
  "role": "primary",
  "dimensions": {
    "width": 300,
    "height": 250,
    "responsive": {"width": false, "height": false},
    "unit": "px"
  }
}

Responsive width (fluid banners):

{
  "role": "primary",
  "dimensions": {
    "min_width": 300,
    "max_width": 970,
    "height": 250,
    "responsive": {"width": true, "height": false},
    "unit": "px"
  }
}

Aspect ratio constrained (native formats):

{
  "role": "primary",
  "dimensions": {
    "aspect_ratio": "16:9",
    "min_width": 300,
    "responsive": {"width": true, "height": true},
    "unit": "px"
  }
}

Physical dimensions (DOOH):

{
  "role": "primary",
  "dimensions": {
    "width": 48,
    "height": 14,
    "responsive": {"width": false, "height": false},
    "unit": "inches"
  }
}

Benefits of the renders structure:

Supports single and multi-render formats uniformly
No string parsing required - structured dimensions
Schema-validated dimensions
Supports responsive and fixed formats equally
Enables proper preview rendering
Allows dimension-based filtering
Supports physical units for DOOH
Clear semantic roles for each rendered piece

Understanding Format Requirements

Traditional IAB format families (display, video, audio, native) are lossy abstractions that don’t scale to emerging formats:

Performance Max spans video, display, search, and native simultaneously
Search ads (RSA) are text-only with high intent context
Conversational AI placements don’t fit traditional categories

The assets array tells you exactly what creative elements are needed:

Video required? Check for asset_type: 'video'
Images required? Check for asset_type: 'image'
Text only? All required assets have asset_type: 'text'

AdCP supports formats across multiple media types:

Video Formats

Standard video (15s, 30s, 60s)
Vertical video for mobile/stories
VAST/VPAID tags
Interactive video

See Video Channel Guide for complete specifications.

Display Formats

Standard IAB sizes (300x250, 728x90, etc.)
Responsive units
Rich media and expandable
HTML5 creative

See Display Channel Guide for complete specifications.

Audio Formats

Streaming audio (15s, 30s, 60s)
Podcast insertion
Companion banners
VAST audio tags

See Audio Channel Guide for complete specifications.

DOOH Formats

Digital billboards
Transit displays
Retail screens
Venue-based impression tracking

See DOOH Channel Guide for complete specifications.

Carousel/Multi-Asset Formats

Product carousels (3-10 items)
Story sequences
Slideshow formats
Frame-based structures

See Carousel Channel Guide for complete specifications.

Multi-Asset & Frame-Based Formats

Some formats like carousels, slideshows, and stories use repeatable asset groups where each frame contains a collection of assets. See the Carousel & Multi-Asset Formats guide for complete documentation on frame-based format patterns.

Reported Metrics

Formats can declare which metrics they produce in delivery reporting via the reported_metrics field. This tells buyers what data to expect when purchasing inventory using this format.

{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "video_30s_hosted"
  },
  "name": "30-Second Hosted Video",
  "reported_metrics": [
    "impressions", "spend", "views", "completed_views",
    "completion_rate", "quartile_data"
  ]
}

Intersection with Product Metrics

Products declare their available metrics via reporting_capabilities.available_metrics. The buyer receives the intersection of format reported_metrics and product available_metrics. impressions and spend are always reported regardless of the intersection — they are implicit in every delivery response. The intersection applies to all other metrics. For example, if a video format declares quartile_data but the product only reports impressions, spend, and clicks, the buyer will not receive quartile data for that product.

When to Omit

If reported_metrics is omitted, the format defers entirely to product-level metric declarations. This is appropriate for formats where the creative type does not inherently constrain which metrics are available (e.g., native formats where metrics depend on the platform).

Common Patterns

Video formats: impressions, spend, views, completed_views, completion_rate, quartile_data Display formats: impressions, spend, clicks, ctr, viewability DOOH formats: impressions, spend, dooh_metrics Social/performance formats: impressions, spend, clicks, ctr, conversions, engagement_rate

Format Cards

Format cards provide visual representations of creative formats for display in browsing and selection interfaces. Creative agents can optionally include card definitions that reference card formats and provide the assets needed to render attractive visual cards.

Card Types

Creative agents should provide at least the standard card, and optionally a detailed card: Standard Card (format_card):

Compact 300x400px card for format browsing
Supports 2x density images for retina displays
Quick visual understanding of format specs

Detailed Card (format_card_detailed, optional):

Responsive layout with text description alongside hero carousel showing format in context
Markdown specifications section below
Full format documentation similar to Yahoo’s ad specs

Structure

{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "video_standard_30s"
  },
  "name": "Standard Video - 30 seconds",
  "type": "video",
  // ... other format fields ...

  "format_card": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "format_card_standard"
    },
    "manifest": {
      "display_name": "30-Second Video",
      "preview_mockup_url": "https://cdn.example.com/format-mockups/video_30s.png",
      "format_type_label": "Video"
    }
  },

  "format_card_detailed": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "format_card_detailed"
    },
    "manifest": {
      "display_name": "Standard 30-Second Video",
      "description": "The Edge A-Logs Horizon (desktop) format is an encompassing...",
      "carousel_images": [
        "https://cdn.example.com/formats/video_30s_context1.jpg",
        "https://cdn.example.com/formats/video_30s_context2.jpg"
      ],
      "specifications_markdown": "# Technical Specifications\n\n..."
    }
  }
}

Rendering Cards

Cards can be rendered in two ways:

Via preview_creative: Pass the card format and manifest to generate a rendered card
Pre-rendered: Creative agents can pre-generate cards and serve them directly

This flexibility allows implementations to choose between dynamic generation or static hosting based on their infrastructure.

Standard Card Formats

The AdCP reference creative agent defines two standard card formats:

format_card_standard (300x400px) - Compact card for format browsing
format_card_detailed (responsive) - Rich card with carousel and full specs

Creative agents can also define custom card formats to highlight unique format capabilities or match their branding. Note: Standard card format definitions are maintained in the creative-agent repository, not in this protocol specification.

When to Include Format Cards

Format cards are optional but recommended for:

Visual formats (display, video, DOOH) where mockups help explain the format
Complex formats with multiple asset requirements
Custom formats that differ from standard specifications
Formats where visual preview aids buyer understanding

Use the detailed card variant when you want to provide comprehensive format documentation similar to ad spec pages.

Client Rendering Guidelines

When displaying formats in UIs, clients should follow this fallback order:

If format_card exists → Render card via preview_creative or display pre-rendered image
If no format_card exists → Render text-only representation (format name + description)
If card rendering fails → Gracefully fall back to text-only representation

This ensures a consistent user experience regardless of what format metadata is available.

Creative Protocol Overview - How formats, manifests, and agents work together
Creative Manifests - Pairing assets with formats
Asset Types - Understanding asset specifications
Channel Guides - Detailed format documentation by media type
Implementing Standard Format Support - For sales agents
list_creative_formats Task - API reference for format discovery

Documentation

​Standard vs Custom Formats

​Standard Formats

​Custom Formats

​Discovering Formats

​Format Authority

​Format Visual Presentation

​Example Showcase

​Referencing Formats

​Structured Format IDs (Required Everywhere)

​Where Structured Format IDs Are Used

​Validation Rules

​Legacy Considerations

​Format Structure

​Asset Discovery

​Typed Asset Requirements

​Asset Overlays

​Rendered Outputs and Dimensions

​Understanding Format Requirements

​Video Formats

​Display Formats

​Audio Formats

​DOOH Formats

​Carousel/Multi-Asset Formats

​Multi-Asset & Frame-Based Formats

​Reported Metrics

​Intersection with Product Metrics

​When to Omit

​Common Patterns

​Format Cards

​Card Types

​Structure

​Rendering Cards

​Standard Card Formats

​When to Include Format Cards

​Client Rendering Guidelines

​Related Documentation

Standard vs Custom Formats

Standard Formats

Custom Formats

Discovering Formats

Format Authority

Format Visual Presentation

Example Showcase

Referencing Formats

Structured Format IDs (Required Everywhere)

Where Structured Format IDs Are Used

Validation Rules

Legacy Considerations

Format Structure

Asset Discovery

Typed Asset Requirements

Asset Overlays

Rendered Outputs and Dimensions

Understanding Format Requirements

Video Formats

Display Formats

Audio Formats

DOOH Formats

Carousel/Multi-Asset Formats

Multi-Asset & Frame-Based Formats

Reported Metrics

Intersection with Product Metrics

When to Omit

Common Patterns

Format Cards

Card Types

Structure

Rendering Cards

Standard Card Formats

When to Include Format Cards

Client Rendering Guidelines

Related Documentation