> ## 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.

# Creative Formats

Creative formats define the structure, requirements, and delivery methods for advertising creatives. Each format specifies what assets are needed, their technical requirements, and how they should be assembled.

For an overview of how formats, manifests, and creative agents work together, see the [Creative Protocol Overview](/dist/docs/2.5.3/creative).

## Standard vs Custom Formats

AdCP defines two categories of formats:

### Standard Formats

Pre-defined, industry-standard specifications provided by the **AdCP Reference Creative Agent** (`https://creative.adcontextprotocol.org`):

* **Simplified**: No platform-specific complexity
* **Portable**: One creative works everywhere
* **Validated**: Pre-tested IAB specifications
* **Discoverable**: Available via `list_creative_formats`
* **Maintained**: Centrally hosted and updated

Standard formats include common IAB ad units (300x250, 728x90), standard video specs (15s, 30s pre-roll), audio formats, DOOH, and more. See the [Creative Channel Guides](/dist/docs/2.5.3/creative/channels/video) for format documentation.

**For sales agents:** Before creating custom format definitions, check the reference creative agent to see if your formats already exist. Most publishers support some standard formats and should reference `https://creative.adcontextprotocol.org`. See [Implementing Standard Format Support](/dist/docs/2.5.3/media-buy/capability-discovery/implementing-standard-formats) for detailed guidance.

### Custom Formats

Publisher-specific formats for unique inventory that doesn't match standard specifications:

* **Unique requirements**: Custom dimensions, special asset needs, or unique technical specs
* **Specialized capabilities**: Platform-specific features not available in standard formats
* **Premium experiences**: Differentiated ad products like takeovers, rich media, or immersive units
* **Custom validation**: Publisher-specific creative review or assembly logic

**When to create custom formats:** Only when you have truly unique requirements that aren't covered by standard formats. Most publishers will reference standard formats for common ad units (300x250, video pre-roll, etc.) and only define custom formats for premium or specialized inventory.

## Discovering Formats

Buyers discover available formats using the `list_creative_formats` task, which returns formats supported by a sales agent.

**Formats can come from two sources:**

1. **Directly from the sales agent** - Custom formats defined by the publisher
2. **Referenced creative agents** - The sales agent points to other creative agents (like the reference agent) for additional format support

**Example discovery response:**

```json theme={null}
{
  "$schema": "https://adcontextprotocol.org/schemas/v2/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 tells buyers: "We support our custom homepage takeover format, PLUS all standard formats from the reference creative agent."

**For sales agents implementing format support:** See [Implementing Standard Format Support](/dist/docs/2.5.3/media-buy/capability-discovery/implementing-standard-formats).

## Format Authority

Each format includes an `agent_url` field pointing to its authoritative source:

```json theme={null}
{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "video_30s_hosted"
  },
  "name": "Standard 30-Second Video"
}
```

The creative agent at that URL is the definitive source for:

* Complete format specifications
* Asset validation rules
* Preview generation
* Format documentation

Buyers query the agent\_url for full format details, validation, and preview capabilities.

## Format Visual Presentation

Formats include two optional fields for visual presentation in format browsing UIs:

### Preview Image

**Field**: `preview_image`
**Purpose**: Thumbnail/card image for format browsing
**Specifications**:

* **Dimensions**: 400×300px (4:3 aspect ratio)
* **Format**: PNG or JPG
* **Use case**: Quick visual identification in format lists/grids

### Example Showcase

**Field**: `example_url`
**Purpose**: Link to full interactive demo/showcase page
**Content**: Publisher-controlled page showing:

* Video walkthroughs of the format
* Interactive demos
* Multiple creative examples
* Technical specifications
* Best practices

**Why this approach?**

* Publishers control how to best showcase complex formats
* No schema limitations on presentation methods
* Handles video, interactive demos, DOOH installations, etc.
* Structured card (preview\_image) + deep link (example\_url) pattern

**Example**:

```json theme={null}
{
  "$schema": "https://adcontextprotocol.org/schemas/v2/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",
  "preview_image": "https://publisher.com/format-cards/homepage-takeover.png",
  "example_url": "https://publisher.com/formats/homepage-takeover-demo"
}
```

## Referencing Formats

**CRITICAL**: AdCP uses structured format ID objects everywhere to avoid parsing ambiguity and handle namespace collisions.

### Structured Format IDs (Required Everywhere)

**ALL format references** use structured format ID objects:

```json theme={null}
{
  "$schema": "https://adcontextprotocol.org/schemas/v2/core/format-id.json",
  "agent_url": "https://creative.adcontextprotocol.org",
  "id": "display_300x250"
}
```

**Why structured objects everywhere?**

* **No parsing needed**: Components are explicit
* **Unambiguous**: Clear separation of namespace and identifier
* **Handles collisions**: Same format ID from different agents are distinct
* **No exceptions**: Simpler mental model - one format\_id pattern everywhere
* **Validation-friendly**: Easy to validate with JSON Schema
* **Extensible**: Can add version or other metadata later

### Where Structured Format IDs Are Used

**Requests:**

* `sync_creatives` - Uploading creative assets
* `build_creative` - Generating creatives via creative agents
* `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:**

1. ✅ Accept structured `format_id` objects in ALL contexts
2. ✅ Return structured `format_id` objects in ALL responses
3. ❌ Reject string format\_ids with clear error messages
4. ❌ Never use string format\_ids in any API contract

**Error handling for invalid format\_id:**

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

1. **Strict validation** (recommended): Reject strings immediately with clear error
2. **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:

```json theme={null}
{
  "$schema": "https://adcontextprotocol.org/schemas/v2/core/format.json",
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "video_30s_hosted"
  },
  "name": "30-Second Hosted Video",
  "type": "video",
  "assets_required": [
    {
      "item_type": "individual",
      "asset_id": "video_file",
      "asset_type": "video",
      "asset_role": "hero_video",
      "required": true,
      "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**: Category (video, display, audio, native, dooh, rich\_media)
* **assets\_required**: Array of asset specifications
* **asset\_role**: Identifies asset purpose (hero\_image, logo, cta\_button, etc.)
* **renders**: Array of rendered outputs with dimensions - see below

### Rendered Outputs and Dimensions

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:

```json theme={null}
{
  "$schema": "https://adcontextprotocol.org/schemas/v2/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):**

```json theme={null}
{
  "$schema": "https://adcontextprotocol.org/schemas/v2/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):

```json theme={null}
{
  "role": "primary",
  "dimensions": {
    "width": 300,
    "height": 250,
    "responsive": {"width": false, "height": false},
    "unit": "px"
  }
}
```

**Responsive width** (fluid banners):

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

**Aspect ratio constrained** (native formats):

```json theme={null}
{
  "role": "primary",
  "dimensions": {
    "aspect_ratio": "16:9",
    "min_width": 300,
    "responsive": {"width": true, "height": true},
    "unit": "px"
  }
}
```

**Physical dimensions** (DOOH):

```json theme={null}
{
  "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

## Format Categories

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](/dist/docs/2.5.3/creative/channels/video) for complete specifications.

### Display Formats

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

See [Display Channel Guide](/dist/docs/2.5.3/creative/channels/display) for complete specifications.

### Audio Formats

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

See [Audio Channel Guide](/dist/docs/2.5.3/creative/channels/audio) for complete specifications.

### DOOH Formats

* Digital billboards
* Transit displays
* Retail screens
* Venue-based impression tracking

See [DOOH Channel Guide](/dist/docs/2.5.3/creative/channels/dooh) for complete specifications.

### Carousel/Multi-Asset Formats

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

See [Carousel Channel Guide](/dist/docs/2.5.3/creative/channels/carousels) 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](/dist/docs/2.5.3/creative/channels/carousels) for complete documentation on frame-based format patterns.

## 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](https://adspecs.yahooinc.com/premium-ads/e2e-horizon-desktop)

### Structure

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

1. **Via `preview_creative`**: Pass the card format and manifest to generate a rendered card
2. **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](https://github.com/adcontextprotocol/creative-agent), 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:

1. **If `format_card` exists** → Render card via `preview_creative` or display pre-rendered image
2. **If only `preview_image` exists** → Display static image (deprecated but supported)
3. **If neither exists** → Render text-only representation (format name + description)
4. **If card rendering fails** → Gracefully fall back to text-only representation

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

## Related Documentation

* [Creative Protocol Overview](/dist/docs/2.5.3/creative) - How formats, manifests, and agents work together
* [Creative Manifests](/dist/docs/2.5.3/creative/creative-manifests) - Pairing assets with formats
* [Asset Types](/dist/docs/2.5.3/creative/asset-types) - Understanding asset specifications
* [Channel Guides](/dist/docs/2.5.3/creative/channels/video) - Detailed format documentation by media type
* [Implementing Standard Format Support](/dist/docs/2.5.3/media-buy/capability-discovery/implementing-standard-formats) - For sales agents
* [list\_creative\_formats Task](/dist/docs/2.5.3/media-buy/task-reference/list_creative_formats) - API reference for format discovery