diff --git a/docs/media-buy/creative-formats.md b/docs/media-buy/creative-formats.md index ec50b22a8..844fcf73d 100644 --- a/docs/media-buy/creative-formats.md +++ b/docs/media-buy/creative-formats.md @@ -6,6 +6,8 @@ title: Creative Formats All creative formats have a unique identifier and specify delivery methods. Formats can require either a single asset or multiple assets for rich media experiences. +**For the complete workflow on format discovery, see the [Creative Lifecycle](./creative-lifecycle#phase-1-format-discovery) documentation.** + ## Standard vs Custom Formats AdCP defines two categories of formats: diff --git a/docs/media-buy/creative-lifecycle.md b/docs/media-buy/creative-lifecycle.md index e2bffb1f9..6dc8c7cea 100644 --- a/docs/media-buy/creative-lifecycle.md +++ b/docs/media-buy/creative-lifecycle.md @@ -4,7 +4,74 @@ title: Creative Lifecycle # Creative Lifecycle -AdCP provides a comprehensive centralized creative library for managing the entire lifecycle of creative assets. This document explains the conceptual model and workflow for creative management using the centralized library approach. +AdCP manages the complete creative lifecycle from initial format discovery through ongoing optimization. This document covers the three main phases: discovering requirements, producing assets, and managing the creative library. + +## Phase 1: Format Discovery + +Before creating any creative assets, you need to understand **what formats are required**. AdCP provides two complementary tools that work together: + +### The Discovery Workflow + +**`get_products`** finds advertising inventory that matches your campaign needs, while **`list_creative_formats`** provides the detailed creative specifications for the formats those products require. + +#### Two Common Approaches: + +**1. Inventory-First** - "What products match my campaign?" +```javascript +// Find products for your campaign +const products = await get_products({ + brief: "Premium video inventory for sports fans", + promoted_offering: "Nike Air Max 2024" +}); +// Products return: formats: ["video_15s_hosted", "homepage_takeover_2024"] + +// Get creative specs for those specific formats +const formatSpecs = await list_creative_formats({ + format_ids: products.products.flatMap(p => p.formats) +}); +// Now you know: video_15s_hosted needs MP4 H.264, 15s, 1920x1080 +// homepage_takeover_2024 needs hero image + logo + headline +``` + +**2. Creative-First** - "What video formats does this publisher support?" +```javascript +// Browse available video formats +const videoFormats = await list_creative_formats({ + type: "video", + category: "standard" +}); +// Returns: video_15s_hosted, video_30s_vast, video_vertical_15s, etc. + +// Find products supporting your creative capabilities +const products = await get_products({ + promoted_offering: "Nike Air Max 2024", + filters: { + format_ids: ["video_15s_hosted", "video_30s_vast"] + } +}); +// Returns only products that accept these specific formats +``` + +### Why Both Tools Matter + +- **Without `list_creative_formats`**: Format IDs from products are meaningless strings +- **Without `get_products`**: You don't know which formats actually have available inventory +- **Together**: You understand both what's available AND what's required + +**Common discovery patterns:** +- **Campaign planning**: Inventory-first approach to find the right audience, then build creative +- **Production planning**: Creative-first approach to understand capabilities, then find compatible inventory +- **Cross-publisher campaigns**: Use standard formats for maximum reach across multiple publishers + +--- + +## Phase 2: Creative Production + +Once you understand format requirements, create the actual creative assets according to the specifications discovered in Phase 1. + +--- + +## Phase 3: Creative Library Management ## The Creative Library Model diff --git a/docs/media-buy/tasks/get_products.md b/docs/media-buy/tasks/get_products.md index 3aa0dc92b..919ce7803 100644 --- a/docs/media-buy/tasks/get_products.md +++ b/docs/media-buy/tasks/get_products.md @@ -7,7 +7,7 @@ Discover available advertising products based on campaign requirements, using na **Response Time**: ~60 seconds (inference/RAG with back-end systems) -**Format Discovery**: Products return format references (IDs only). Use [`list_creative_formats`](./list_creative_formats) to get full format specifications including requirements, file types, and dimensions. +**Format Discovery**: Products return format references (IDs only). Use [`list_creative_formats`](./list_creative_formats) to get full format specifications. **See [Creative Lifecycle](../creative-lifecycle#phase-1-format-discovery) for the complete workflow.** **Request Schema**: [`/schemas/v1/media-buy/get-products-request.json`](/schemas/v1/media-buy/get-products-request.json) **Response Schema**: [`/schemas/v1/media-buy/get-products-response.json`](/schemas/v1/media-buy/get-products-response.json) diff --git a/docs/media-buy/tasks/list_creative_formats.md b/docs/media-buy/tasks/list_creative_formats.md index ee332be43..dc0ed7811 100644 --- a/docs/media-buy/tasks/list_creative_formats.md +++ b/docs/media-buy/tasks/list_creative_formats.md @@ -5,7 +5,9 @@ sidebar_position: 2 # list_creative_formats -Discover all supported creative formats in the system. +Discover all supported creative formats in the system. + +**See [Creative Lifecycle](../creative-lifecycle#phase-1-format-discovery) for the complete workflow on how this tool works with `get_products` for format discovery.** **Response Time**: ~1 second (simple database lookup) @@ -19,6 +21,7 @@ Discover all supported creative formats in the system. | `type` | string | No | Filter by format type (e.g., `"audio"`, `"video"`, `"display"`) | | `category` | string | No | Filter by category (`"standard"` or `"custom"`) | | `standard_only` | boolean | No | Only return standard formats (deprecated, use `category: "standard"`) | +| `format_ids` | string[] | No | Filter by specific format IDs (e.g., from `get_products` response) | ## Response (Message) @@ -60,6 +63,7 @@ The message is returned differently in each protocol: - **requirements**: Format-specific requirements (varies by format type) - **assets_required**: Array of required assets with `asset_role` identifiers + ## Protocol-Specific Examples The AdCP payload is identical across protocols. Only the request/response wrapper differs. @@ -138,6 +142,81 @@ The AdCP payload is identical across protocols. Only the request/response wrappe } ``` +### Example 3: Reverse Workflow (Product-First) + +#### MCP Request - Get specs for specific format IDs +```json +{ + "tool": "list_creative_formats", + "arguments": { + "format_ids": ["video_15s_hosted", "video_30s_vast", "display_300x250"] + } +} +``` + +#### MCP Response +```json +{ + "message": "Found 3 specific formats. These are the exact creative requirements for your available inventory.", + "formats": [ + { + "format_id": "video_15s_hosted", + "name": "15-Second Hosted Video", + "type": "video", + "category": "standard", + "duration": "15s", + "accepts_3p_tags": false, + "assets_required": [ + { + "asset_id": "video_file", + "asset_type": "video", + "asset_role": "hero_video", + "required": true, + "requirements": { + "duration": "15s", + "format": "MP4 H.264", + "resolution": ["1920x1080", "1280x720"], + "max_file_size_mb": 30 + } + } + ] + }, + { + "format_id": "video_30s_vast", + "name": "30-Second VAST Video", + "type": "video", + "category": "standard", + "duration": "30s", + "accepts_3p_tags": true, + "delivery": { + "method": "VAST", + "versions": ["3.0", "4.0", "4.1", "4.2"] + } + }, + { + "format_id": "display_300x250", + "name": "Medium Rectangle", + "type": "display", + "category": "standard", + "dimensions": "300x250", + "accepts_3p_tags": false, + "assets_required": [ + { + "asset_id": "banner_image", + "asset_type": "image", + "asset_role": "hero_image", + "required": true, + "width": 300, + "height": 250, + "acceptable_formats": ["jpg", "png", "gif"], + "max_file_size_kb": 200 + } + ] + } + ] +} +``` + ### MCP Response **Message:** @@ -368,14 +447,16 @@ I found 15 display formats including standard IAB sizes and innovative formats l ## Usage Notes -- Use this tool to understand what creative formats are supported before creating assets -- Standard formats follow IAB specifications for maximum compatibility -- Non-standard formats may offer enhanced features but have limited inventory -- For composite formats (like carousels), check `assets_required` for all needed components -- Requirements vary by format type: - - Audio formats specify duration, file types, and bitrate - - Video formats include resolution, aspect ratio, and codec requirements - - Display formats define dimensions, file types, and size limits +- **Primary use case**: Get creative specifications after `get_products` returns format IDs +- **Format IDs are just strings** until you get their specifications from this tool +- **Standard formats** follow IAB specifications and work across multiple publishers +- **Custom formats** (like "homepage_takeover") are publisher-specific with unique requirements +- **The `format_ids` parameter** is the most efficient way to get specs for specific formats returned by products +- **Asset requirements vary by format type**: + - Audio formats: duration, file types, bitrate specifications + - Video formats: resolution, aspect ratio, codec, delivery method + - Display formats: dimensions, file types, file size limits + - Rich media formats: multiple assets with specific roles and requirements ## Implementation Guide diff --git a/static/schemas/v1/media-buy/list-creative-formats-request.json b/static/schemas/v1/media-buy/list-creative-formats-request.json index 56d9a4af4..e365b283f 100644 --- a/static/schemas/v1/media-buy/list-creative-formats-request.json +++ b/static/schemas/v1/media-buy/list-creative-formats-request.json @@ -19,6 +19,18 @@ "standard_only": { "type": "boolean", "description": "Only return IAB standard formats" + }, + "category": { + "type": "string", + "description": "Filter by format category", + "enum": ["standard", "custom"] + }, + "format_ids": { + "type": "array", + "description": "Filter by specific format IDs (e.g., from get_products response)", + "items": { + "type": "string" + } } }, "additionalProperties": false