AdCP — build

Transform, generate, or retrieve a creative manifest for a specific format. To render a visual preview of the resulting manifest, pass it to preview_creative. Supports three modes:

Generation: Create a manifest from a brief or seed assets (message + creative_manifest)
Transformation: Adapt an existing manifest to a different format (creative_manifest + target_format_id)
Library retrieval: Resolve a creative_id from the agent’s library into a manifest with ad-serving assets

For generation and transformation, build_creative takes a creative manifest as input and produces a creative manifest as output. For library retrieval, provide a creative_id (from list_creatives) and the agent resolves it from its library. For information about legacy format IDs and how to reference formats, see Creative Formats - Referencing Formats. On the 3.1 canonical path, creative agents advertise buildable outputs through get_adcp_capabilities.creative.supported_formats[]; targetable entries SHOULD include a stable capability_id, and buyers pass that value as target_format_id.id (or target_format_ids[N].id) when calling build_creative.

Request parameters

Parameter	Type	Required	Description
`message`	string	No	Natural language instructions for the creative agent. For generation, this provides creative direction. For transformation, this guides how to adapt the creative. For refinement, this describes the desired changes.
`creative_manifest`	object	No	Creative manifest to transform or generate from (see Creative Manifest). For pure generation, this should include the target format_id and any required input assets. For transformation, this is the complete creative to adapt. When `creative_id` is provided, the agent resolves the creative from its library and this field is ignored.
`creative_id`	string	No	Reference to a creative in the agent’s library. The creative agent resolves this to a manifest from its library. Use this instead of `creative_manifest` when retrieving an existing creative for tag generation or format adaptation.
`concept_id`	string	No	Creative concept containing the creative. Used to disambiguate when the same `creative_id` exists in multiple concepts.
`media_buy_id`	string	No	Buyer’s media buy reference for tag generation context. When the creative agent is also the ad server (e.g., CM360), this provides the trafficking context needed to generate placement-specific tags. Omit when the platform generates tags at the creative level (Flashtalking, Celtra). This is the buyer’s reference — the seller-assigned identifier from `create_media_buy`.
`package_id`	string	No	Buyer’s package or line item reference within the media buy. Used with `media_buy_id` when the creative agent needs line-item-level context. Omit to get a tag not scoped to a specific package — the ad server may return the same tag regardless.
`target_format_id`	object	Conditional	Single format ID to generate. Object with `agent_url` and `id` fields. For 3.1 canonical creative-agent routing, `id` is the advertised `creative.supported_formats[].capability_id`; legacy named-format IDs remain accepted during the migration window. Mutually exclusive with `target_format_ids` — provide exactly one.
`target_format_ids`	array	Conditional	Array of format IDs to generate in a single call. Each element is an object with `agent_url` and `id` fields. For 3.1 canonical creative-agent routing, each `id` is an advertised `creative.supported_formats[].capability_id`; legacy named-format IDs remain accepted during the migration window. Mutually exclusive with `target_format_id` — provide exactly one. Returns one manifest per format.
`brand`	object	No	Brand reference with `domain` field. Resolves brand identity via `/.well-known/brand.json`. Provides brand-level context (colors, logos, tone).
`quality`	string	No	Quality tier: `"draft"` (fast, lower-fidelity for iteration) or `"production"` (full quality for final delivery). If omitted, the creative agent uses its own default.
`item_limit`	integer	No	Maximum number of catalog items to use within one creative. Caps generation cost for catalog-driven formats (e.g. a 6-card carousel built from a 1,000-product catalog). Distinct from `max_creatives`, which fans out across items.
`transformer_id`	string	No	Select one transformer (discovered via `list_transformers`) to perform the build. The requested target format(s) MUST be a subset of that transformer’s `output_format_ids`. The transformer’s `per_unit` rate is the pricing source for the build.
`config`	object	No	Typed configuration bag keyed to the selected transformer’s `params[].field` (e.g. `{ "voice": "isaac", "speaking_rate": 1.1 }`). The creative agent MUST reject unknown keys and out-of-range values with field-attributed errors (strict validation) — vendor-specific knobs that are not declared params go in `ext`. Only meaningful with `transformer_id`.
`max_creatives`	integer	No	Catalog fan-out axis: produce up to N distinct creatives, one per catalog item (a sample — e.g. 5 of 150). Distinct from `item_limit`, which caps items used within a single creative. Mutually exclusive with `refine_from_build_variant_id`. Triggers the `BuildCreativeVariantSuccess` response shape. Supported only when the agent advertises `creative.multiplicity.supports_catalog_fanout`; values above `max_creatives_limit` are clamped (shortfall via `items_returned` < `items_total`), not rejected.
`signal_conditions`	array	No	Signal fan-out axis: produce one distinct creative per signal condition, each kept and trafficked with its own targeting (a rain creative AND a sun creative). Each item is a SignalTargeting. Sibling to `max_creatives`; composes with it (catalog × conditions). Advisory at this layer (#5280) — trafficking-compatibility is enforced sales-side via `SIGNAL_TARGETING_INCOMPATIBLE`. Supported only when the agent advertises `creative.multiplicity.supports_signal_fanout`; counts above `max_signal_conditions_limit` are clamped. See Signal fan-out.
`selection_strategy`	string	No	How the agent samples when `max_creatives` < eligible items: `audience_relevance` (user-side, ranks by the same `signal_ref` pointers), `contextual_fit` (content-side, same mechanism with a context signal), `performance` (historical delivery), `proximity`, `inventory_priority` (seller-side), or `random` (default). Ordering surfaces on `rank`/`recommended`. Supported set in `creative.multiplicity.selection_strategies[]`.
`max_variants`	integer	No	Number of alternative renders to produce per creative (best-of-N). Default `1`. You pay for every produced variant; keeping one or more is a separate trafficking step. Supported only when the agent advertises `creative.multiplicity.supports_variants`; values above `max_variants_limit` are clamped.
`variant_axis`	object	No	Describes the dimension along which variants differ. Object with `dimension` (`voice` \| `theme` \| `best_of_n` \| `transformer_config` \| `custom`), optional `values[]` (explicit values to enumerate along the axis), optional `field` (the `config` param to sweep — required when `dimension` is `transformer_config`), and optional `label`.
`keep_mode`	string	No	Advisory hint to the agent on how many variants you intend to keep: `"keep_all"`, `"keep_one"`, or `"keep_some"`. Default `"keep_all"`. Advisory only — you are billed for all produced variants regardless. The response echoes `keep_mode_applied` so you have confirmation the hint was received (audit trail for billing disputes).
`evaluator`	object	No	Experimental (status; feature id `creative.evaluator`). Advisory evaluator (Evaluator Spec) driving a gate-then-rank pipeline over the agent’s best-of-N: one source form (`exemplars` / account-arranged `evaluator_id` / `agent_url`), an optional hard `feature_requirement[]` gate (drop fails — internal pruning of recommended leaves, never a block on an already-produced billable leaf), an explicit `rank_by` ordering (`[{feature_id, direction: maximize\|minimize}]`), and an allowlisted `feature_agent` pointer. Feature discovery uses `get_adcp_capabilities` `governance.creative_features`; the evaluator returns those same feature IDs in `variants[].eval.features[]`. `evaluator_id` is not discovered from that catalog; it is a pre-provisioned account preset. External agents (`feature_agent.agent_url` / `agent_url`) MUST be in the seller’s `creative_policy.accepted_verifiers[]` — off-list → `EVALUATOR_AGENT_NOT_ACCEPTED`. Requires `creative.supports_evaluator`; otherwise ignored. Populates the per-leaf `variants[].eval` block. See `variants[].eval` and Evaluator authentication.
`refine_from_build_variant_id`	string	No	Refine a prior produced variant: re-build from its `build_variant_id` applying the NL instruction in `message` plus any `config` delta, returning new lineage-linked variants (never a mutation). `transformer_id` and target format(s) are inherited from the parent. Composes with `max_variants`/`variant_axis`; mutually exclusive with `max_creatives`. Requires `creative.supports_refinement` — otherwise `UNSUPPORTED_FEATURE`; an unknown/no-longer-retained ref is `REFERENCE_NOT_FOUND` (`error.field` = `refine_from_build_variant_id`). See Refinement.
`mode`	string	No	`"execute"` (default) produces and bills. `"estimate"` is a dry run — produces and bills nothing, returns a `BuildCreativeEstimate` cost band (`cost_low`/`cost_high`) computed against this request’s inputs. Requires `creative.supports_spend_controls`. See Spend controls.
`max_spend`	object	No	Hard per-call spend ceiling `{ amount, currency }`. The agent produces leaves until the next would exceed `amount`, then stops and returns the partial result with `budget_status: "capped"`. Requires `creative.supports_spend_controls`. Caps one call — bound refinement loops buyer-side. See Spend controls.
`include_preview`	boolean	No	When true, requests preview renders alongside the manifest. Agents that support this return a `preview` object in the response. Agents that don’t simply omit it.
`preview_inputs`	array	No	Input sets for preview generation when `include_preview` is true. Each entry has `name` (required), optional `macros`, and optional `context_description`. If omitted, the agent generates a single default preview. Only supported with `target_format_id` (single-format) — ignored for multi-format requests.
`preview_quality`	string	No	Render quality for inline previews: `"draft"` or `"production"`. Independent of the build `quality` — you can build at draft and preview at production, or vice versa. Only used when `include_preview` is true.
`preview_output_format`	string	No	Output format for preview renders: `"url"` (default) or `"html"`. Only used when `include_preview` is true.
`macro_values`	object	No	Macro values to pre-substitute into the output manifest’s assets. Keys are universal macro names (e.g., `CLICK_URL`, `CACHEBUSTER`); values are the literal substitution strings. The creative agent translates universal macros to its platform’s native syntax. Macros not provided here remain as `{MACRO}` placeholders for the sales agent to resolve at serve time.
`account`	AccountRef	No	Account reference for pricing and billing. When present, the creative agent applies account-specific pricing from the rate card, records the build against the account, and can enforce quotas. Required by creative agents that charge for their services.
`push_notification_config`	object	No	Operation-scoped webhook configuration for async terminal completion/failure notifications when `build_creative` returns `submitted`. Submitted tasks remain pollable via `get_task_status` whether or not this field is present; agents MUST NOT return `submitted` solely because this field is present.

Pricing response fields

When the creative agent charges and account is provided, the response includes pricing fields:

Field	Type	Description
`pricing_option_id`	string	Which rate card pricing option was applied
`vendor_cost`	number	Cost incurred for this build. May be 0 for CPM-priced creatives where cost accrues at serve time.
`currency`	string	ISO 4217 currency code
`consumption`	object	Structured consumption details — `tokens`, `images_generated`, `renders`, `duration_seconds`. See `creative-consumption.json`. Informational for cost verification; `vendor_cost` is the billing source of truth.

For async builds (status: "working" with context_id polling), pricing fields appear on the final completed response only.

Recipe identity

Agents MAY return a top-level recipe_hash on single-format success responses, and MAY return variants[].recipe_hash on multiplicity/refinement leaves. Multi-format creative_manifests[] responses do not carry recipe_hash in this revision; request the variant shape (max_variants) when you need per-output recipe identities. The value is an ETag-style identity for the build-determining inputs: agent-computed, opaque, and scoped to that agent. Buyers can compare it only across responses from the same agent. recipe_hash identifies the input recipe, not the output bytes or legal/disclosure envelope. A nondeterministic build can return different pixels, tags, or variants with the same recipe_hash; the value means “same instructions,” not “same creative.” For fan-out responses, best-of-N leaves produced from the same recipe SHOULD share the same value so clients can group alternatives by their shared source. When both recipe_hash and build_variant_id appear, build_variant_id identifies the output leaf and lineage while recipe_hash identifies the input recipe; neither implies the other. The build-to-delivery performance join still uses the lineage identifiers that survive trafficking, not recipe_hash alone. Important: Required input assets should be included in the creative_manifest.assets object, not as separate task parameters. The format definition specifies what assets it requires. Catalog context for dynamic creatives should be provided via the creative_manifest.assets map.

Evaluator authentication

build_creative.evaluator selects or calibrates the evaluator; it does not authenticate the evaluator call. Do not put evaluator API keys, bearer tokens, client secrets, Authorization values, JWKs, JWKS documents, or JWKS URIs in evaluator, context, ext, or any other payload field. Credential- or trust-material payload keys are non-conforming and should be rejected with CREDENTIAL_IN_ARGS. When evaluator.agent_url or evaluator.feature_agent.agent_url names an external evaluator, the producing creative agent calls that evaluator’s get_creative_features endpoint using the normal AdCP transport authentication channel. The evaluator authenticates the creative/seller agent as caller via RFC 9421 request signing and JWKS discovery, mTLS, or a pre-provisioned Bearer/API-key credential. Payload fields such as agent_url, account, context, and ext are not identity assertions and must not be treated as credentials. The allowlist check still happens first: an external evaluator URL that is not in creative_policy.accepted_verifiers[] is rejected with EVALUATOR_AGENT_NOT_ACCEPTED before any outbound call. Buyers learn accepted evaluator URLs from the seller’s published creative_policy.accepted_verifiers[] where a media-buy/product context exposes one, or from account provisioning in standalone creative-agent integrations. If the URL is on-list but the evaluator is unreachable or rejects the creative agent’s transport authentication, the build degrades to seller-default ranking with an advisory errors[] note rather than failing the entire build.

Generation controls

For generative formats, two optional parameters control the generation process:

quality: Controls generation fidelity. Use "draft" for rapid iteration (reviewing layouts, copy, composition) and "production" for final renders. Draft outputs may use lower-resolution images, simplified effects, or placeholder elements. To produce a production version of a draft you like, pass the draft’s output manifest back as creative_manifest with quality: "production". Note: preview_creative also accepts quality to control render fidelity independently — see Previewing generative creative.
item_limit: For catalog-driven formats, caps how many catalog items are used during generation. A catalog might contain 1,000 products but you only need 4 hero images. The creative agent selects top items based on relevance or catalog ordering. When item_limit exceeds the format’s max_items (from catalog requirements), the creative agent should use the lesser of the two. If omitted, the creative agent decides based on catalog size and format requirements.

Use cases

Pure generation (creating from scratch)

For pure generation, provide a minimal source manifest with the required input assets defined by the format:

{
  "$schema": "/schemas/media-buy/build-creative-request.json",
  "idempotency_key": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
  "message": "Create a banner promoting our winter sale with a warm, inviting feel",
  "target_format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_300x250_generative"
  },
  "brand": {
    "domain": "mybrand.com"
  },
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_300x250_generative"
    },
    "assets": {
      "offering_catalog": {
        "asset_type": "catalog",
        "type": "offering",
        "items": [
          {
            "offering_id": "winter-sale",
            "name": "Winter Sale Collection",
            "description": "50% off all winter items"
          }
        ]
      }
    }
  }
}

Transformation (adapting existing creative)

For transformation, provide the complete source manifest:

{
  "$schema": "/schemas/media-buy/build-creative-request.json",
  "idempotency_key": "b2c3d4e5-f6a7-4890-b123-456789abcdef",
  "message": "Adapt this creative for mobile, making the text larger and CTA more prominent",
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_300x250"
    },
    "assets": {
      "banner_image": {
        "asset_type": "image",
        "url": "https://cdn.example.com/original-banner.png",
        "width": 300,
        "height": 250
      },
      "headline": {
        "asset_type": "text",
        "content": "Winter Sale - 50% Off"
      }
    }
  },
  "target_format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_mobile_320x50"
  }
}

Format resizing

Transform an existing creative to a different size:

{
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_728x90"
    },
    "assets": { /* complete assets */ }
  },
  "target_format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_300x250"
  }
}

Library retrieval

Retrieve a creative from the agent’s library and resolve it into a manifest with ad-serving assets. Use this when you know the creative_id from list_creatives and want the creative agent to produce a delivery-ready manifest with tags (HTML, JavaScript, or VAST):

{
  "$schema": "/schemas/media-buy/build-creative-request.json",
  "idempotency_key": "c3d4e5f6-a7b8-4901-c234-56789abcdef0",
  "creative_id": "ft_88201",
  "concept_id": "concept_holiday_2026",
  "target_format_id": {
    "agent_url": "https://creative.example.com",
    "id": "display_static",
    "width": 300,
    "height": 250
  },
  "macro_values": {
    "CLICK_URL": "https://publisher.example.com/click/abc123"
  }
}

Response — the manifest includes ad-serving tag assets with macros resolved:

{
  "$schema": "/schemas/media-buy/build-creative-response.json",
  "status": "completed",
  "recipe_hash": "rh_scope3_9f2c7a1d5b3e",
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.example.com",
      "id": "display_static",
      "width": 300,
      "height": 250
    },
    "assets": {
      "ad_tag": {
        "asset_type": "javascript",
        "content": "<script src=\"https://cdn.example.com/frameworks/js/sdk.js\"></script><script>AdSDK.createBanner({clickTag:'https://publisher.example.com/click/abc123',width:300,height:250,id:'ft_88201_{CACHEBUSTER}'});</script>"
      },
      "clickthrough_url": {
        "asset_type": "url",
        "url": "https://acmecorp.example.com/holiday-sale?campaign={MEDIA_BUY_ID}"
      }
    }
  }
}

The CLICK_URL macro was substituted with the provided value; CACHEBUSTER remains as a placeholder for the sales agent to resolve at serve time. Do not use recipe_hash to deduplicate ad tags, prove legal/disclosure equivalence, or join build results to served delivery data. Use build_variant_id and the promoted creative_id for lineage and reporting.

Cross-agent workflow: When creative generation and media buying are handled by different agents, use build_creative on the creative agent to produce a manifest with tags, then sync_creatives on the sales agent to upload it. When the sales agent implements both protocols, this happens on a single endpoint — see Creative capabilities on sales agents.

Multi-format generation

Generate creatives for multiple formats in a single call using target_format_ids. The agent produces one manifest per format from the same source assets and brief:

{
  "$schema": "/schemas/media-buy/build-creative-request.json",
  "idempotency_key": "d4e5f6a7-b8c9-4012-d345-6789abcdef01",
  "message": "Create display banners for our spring campaign",
  "target_format_ids": [
    {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_static",
      "width": 300,
      "height": 250
    },
    {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_static",
      "width": 728,
      "height": 90
    },
    {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_static",
      "width": 320,
      "height": 50
    }
  ],
  "brand": {
    "domain": "acmecorp.com"
  },
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_static"
    },
    "assets": {
      "banner_image": {
        "asset_type": "image",
        "url": "https://cdn.acmecorp.com/spring-hero.png",
        "width": 1200,
        "height": 628
      },
      "headline": {
        "asset_type": "text",
        "content": "Spring Collection Now Available"
      },
      "clickthrough_url": {
        "asset_type": "url",
        "url": "https://acmecorp.example.com/spring?campaign={MEDIA_BUY_ID}"
      }
    }
  }
}

The response uses creative_manifests (array) instead of creative_manifest (singular). Each manifest is a complete creative manifest with its own format_id, ready for sync_creatives or preview_creative:

{
  "$schema": "/schemas/media-buy/build-creative-response.json",
  "creative_manifests": [
    {
      "format_id": {
        "agent_url": "https://creative.adcontextprotocol.org",
        "id": "display_static",
        "width": 300,
        "height": 250
      },
      "assets": {
        "banner_image": {
          "asset_type": "image",
          "url": "https://cdn.creative-agent.com/generated/spring_300x250.png",
          "width": 300,
          "height": 250
        },
        "headline": { "asset_type": "text", "content": "Spring Collection Now Available" },
        "clickthrough_url": { "asset_type": "url", "url": "https://acmecorp.example.com/spring?campaign={MEDIA_BUY_ID}" }
      }
    },
    {
      "format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "display_static", "width": 728, "height": 90 },
      "assets": { /* same structure, adapted for 728x90 */ }
    },
    {
      "format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "display_static", "width": 320, "height": 50 },
      "assets": { /* same structure, adapted for 320x50 */ }
    }
  ]
}

Multi-format requests are atomic — if any format fails (e.g., FORMAT_NOT_SUPPORTED), the entire request fails with an error response. The response array order corresponds to the target_format_ids request order. Match manifests to requested formats by array position or by comparing the format_id on each manifest.

Multi-format workflow

After a multi-format build, preview all results using preview_creative batch mode. Each element of creative_manifests in the build response becomes a creative_manifest in the batch preview request:

{
  "request_type": "batch",
  "quality": "draft",
  "requests": [
    { "creative_manifest": { /* 300x250 manifest from build response */ } },
    { "creative_manifest": { /* 728x90 manifest from build response */ } },
    { "creative_manifest": { /* 320x50 manifest from build response */ } }
  ]
}

To refine a single format from a multi-format build, call build_creative again with target_format_id (singular) and pass back that format’s manifest. You don’t need to rebuild all formats — just iterate on the one that needs work.

Multi-format requests with include_preview: true generate one default preview per format. Custom preview_inputs are only supported with single-format requests. For multi-format builds where you need context-specific previews (device variants, different contexts), use a separate preview_creative batch call after building.

Transformers & variants

Select a transformer (discovered via list_transformers) with transformer_id, supply a typed config keyed to its params, and ask for alternatives with max_variants. The agent returns the variant response: creatives[], each holding a variants[] array. Read recommended / rank to surface the agent’s best-of-N pick; traffic the variant(s) you want by their build_variant_id. Resolutions and quality tiers go on target_format_ids (or quality), not on variant_axis — variants are alternatives for the same format.

import { testAgent } from '@adcp/sdk/testing';
import { BuildCreativeResponseSchema } from '@adcp/sdk';

const result = await testAgent.buildCreative({
  account: { account_id: 'acct_acme' },
  transformer_id: 'audiostack_voiceover',
  config: { voice: 'isaac', speaking_rate: 1.1, mastering_preset: 'podcast' },
  target_format_id: { agent_url: 'https://creative.audiostack.example', id: 'audio_vo' },
  creative_manifest: {
    format_id: { agent_url: 'https://creative.audiostack.example', id: 'script' },
    assets: { script: { asset_type: 'text', content: 'Discover the new winter collection.' } },
  },
  max_variants: 3,
  variant_axis: { dimension: 'best_of_n', label: 'Read takes' },
  keep_mode: 'keep_one',
  idempotency_key: '0c1d2e3f-4a5b-6c7d-8e9f-a0b1c2d3e4f5',
});

const parsed = BuildCreativeResponseSchema.parse(result);
for (const creative of parsed.creatives ?? []) {
  for (const variant of creative.variants) {
    console.log(variant.build_variant_id, variant.rank, variant.recommended, variant.vendor_cost);
  }
}

import asyncio
from adcp.testing import test_agent
from adcp import BuildCreativeResponse

async def main():
    result = await test_agent.build_creative(
        account={"account_id": "acct_acme"},
        transformer_id="audiostack_voiceover",
        config={"voice": "isaac", "speaking_rate": 1.1, "mastering_preset": "podcast"},
        target_format_id={"agent_url": "https://creative.audiostack.example", "id": "audio_vo"},
        creative_manifest={
            "format_id": {"agent_url": "https://creative.audiostack.example", "id": "script"},
            "assets": {"script": {"asset_type": "text", "content": "Discover the new winter collection."}},
        },
        max_variants=3,
        variant_axis={"dimension": "best_of_n", "label": "Read takes"},
        keep_mode="keep_one",
        idempotency_key="0c1d2e3f-4a5b-6c7d-8e9f-a0b1c2d3e4f5",
    )
    parsed = BuildCreativeResponse.model_validate(result)
    for creative in parsed.creatives or []:
        for variant in creative.variants:
            print(variant.build_variant_id, variant.rank, variant.recommended, variant.vendor_cost)

asyncio.run(main())

You pay for all three takes (per_unit × 3); keep_mode is advisory. Keeping is a separate trafficking step on the chosen build_variant_id — use that id as the creative_id when promoting the produced manifest through sync_creatives. The kept variant then lazily earns a creative record whose creative_id is the build leaf id and flows to report_usage and delivery reporting.

Paid build with pricing

When the creative agent charges and account is provided, the response includes pricing fields. The agent selects the applicable pricing option server-side based on the account’s rate card and the work performed — the buyer does not pass pricing_option_id in the request. Per-unit pricing (transformation agent):

{
  "$schema": "/schemas/media-buy/build-creative-request.json",
  "idempotency_key": "e5f6a7b8-c9d0-4123-e456-789abcdef012",
  "account": { "account_id": "acct_acme_creative" },
  "creative_id": "cr_hero_banner",
  "target_format_id": {
    "agent_url": "https://creative.example.com",
    "id": "display_728x90"
  }
}

{
  "$schema": "/schemas/media-buy/build-creative-response.json",
  "status": "completed",
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.example.com",
      "id": "display_728x90"
    },
    "assets": {
      "ad_tag": {
        "content": "<div data-adcp-creative='cr_hero_banner' style='width:728px;height:90px;'>...</div>"
      }
    }
  },
  "pricing_option_id": "po_standard_per_format",
  "vendor_cost": 2.00,
  "currency": "USD",
  "consumption": {
    "renders": 1
  }
}

The pricing_option_id corresponds to one of the options from list_creatives. The buyer passes it in report_usage for reconciliation. CPM pricing (ad server) — vendor_cost is 0 at build time because cost accrues when impressions are served:

{
  "$schema": "/schemas/media-buy/build-creative-response.json",
  "status": "completed",
  "creative_manifest": { "..." : "..." },
  "pricing_option_id": "po_video_cpm",
  "vendor_cost": 0,
  "currency": "USD"
}

Response format

Single-format response

When the request uses target_format_id, the response contains a single creative manifest:

{
  "$schema": "/schemas/media-buy/build-creative-response.json",
  "status": "completed",
  "recipe_hash": "rh_winter_300x250_4c2a",
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_300x250"
    },
    "assets": {
      "offering_catalog": {
        "asset_type": "catalog",
        "type": "offering",
        "catalog_id": "winter-sale"
      },
      "banner_image": {
        "asset_type": "image",
        "url": "https://cdn.example.com/generated-banner.png",
        "width": 300,
        "height": 250
      },
      "headline": {
        "asset_type": "text",
        "content": "50% Off Winter Sale"
      },
      "clickthrough_url": {
        "asset_type": "url",
        "url": "https://mybrand.example.com/winter-sale?campaign={MEDIA_BUY_ID}"
      }
    }
  }
}

Multi-format response

When the request uses target_format_ids, the response contains an array of creative manifests:

{
  "$schema": "/schemas/media-buy/build-creative-response.json",
  "creative_manifests": [
    {
      "format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "display_static", "width": 300, "height": 250 },
      "assets": { /* ... */ }
    },
    {
      "format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "display_static", "width": 728, "height": 90 },
      "assets": { /* ... */ }
    }
  ]
}

Variant response

When the request uses max_creatives, max_variants > 1, variant_axis, or refine_from_build_variant_id, the agent returns the BuildCreativeVariantSuccess shape — the third success shape (oneOf member 3 of 6) alongside the single- and multi-format responses, which are unchanged and still used when you build one creative with one variant.

No fallback. If you send any of max_creatives, max_variants > 1, variant_axis, or refine_from_build_variant_id, you must handle creatives[] — you will not get creative_manifest/creative_manifests back. There is no automatic downgrade to the single/multi shapes.

{
  "$schema": "/schemas/media-buy/build-creative-response.json",
  "status": "completed",
  "creatives": [
    {
      "build_creative_id": "bc_card_01",
      "catalog_item_ref": { "catalog_type": "product", "item_id": "sku_winter_parka" },
      "variants": [
        {
          "build_variant_id": "bv_card01_a",
          "recipe_hash": "rh_card01_bestofn_7b91",
          "creative_manifest": { "format_id": { "agent_url": "https://creative.example.com", "id": "display_300x250" }, "assets": { "...": "..." } },
          "variant_axis_value": "take_1",
          "recommended": true,
          "rank": 1,
          "pricing_option_id": "po_per_image",
          "vendor_cost": 0.40,
          "currency": "USD",
          "consumption": { "images_generated": 1 }
        },
        {
          "build_variant_id": "bv_card01_b",
          "recipe_hash": "rh_card01_bestofn_7b91",
          "creative_manifest": { "format_id": { "agent_url": "https://creative.example.com", "id": "display_300x250" }, "assets": { "...": "..." } },
          "variant_axis_value": "take_2",
          "recommended": false,
          "rank": 2,
          "pricing_option_id": "po_per_image",
          "vendor_cost": 0.40,
          "currency": "USD",
          "consumption": { "images_generated": 1 }
        }
      ]
    }
  ],
  "items_total": 150,
  "items_returned": 5,
  "vendor_cost": 4.00,
  "currency": "USD"
}

The creatives[] array above is abbreviated to one of the 5 returned groups; the aggregate vendor_cost of $4.00 covers all 5 groups × 2 variants ×$ 0.40 — it equals the sum of every produced leaf’s vendor_cost, not just the leaves shown.

creatives[]: One entry per built creative group. With max_creatives, there is one entry per sampled catalog item (catalog_item_ref identifies which item); without catalog fan-out there is a single entry. Treat this as the produced group set; choose among alternatives inside each group’s variants[].
creatives[].build_creative_id: Identifies a built creative within this response.
creatives[].catalog_item_ref: Present on catalog fan-out — an object identifying the source catalog item via item_id (plus optional catalog_type).
creatives[].signal_condition: Present on signal fan-out — the SignalTargeting condition this creative group is FOR (e.g. weather=rain). Shares signal_ref identity with sales-side package targeting so the sales agent can match and reject incompatible assignments.
creatives[].errors[]: Present only on a failed catalog item — catalog fan-out is non-atomic, so a failed item is returned as a creatives[] entry carrying errors[] and no variants[], without failing the batch.
creatives[].variants[]: The choose-among alternatives produced for this creative group. Length is at most max_variants. Each variant carries its own complete creative_manifest.
variants[].build_variant_id: Identifies a single variant — the leaf-level lineage anchor. This is its own namespace — never reuse a preview_id (a preview_creative render) or a served variant_id (a delivery-time identifier) here. You traffic a chosen build by passing its build_variant_id.
variants[].recipe_hash: Optional ETag-style identity for the build-determining inputs that produced the leaf. It is agent-computed, opaque, and comparable only within the same agent. Best-of-N leaves from the same source recipe SHOULD share a value. It is useful for cache transparency, cost-avoidance hints, and recipe-level grouping, but it is not output equality, not legal/disclosure equivalence, and not the build-to-delivery join.
variants[].parent_build_variant_id: Present only on a refined variant (Refinement) — the build_variant_id of the source it was refined from. Absent for first-generation builds.
variants[].variant_axis_value: The value of the variant_axis dimension this variant represents (e.g. a voice, a theme).
variants[].recommended / variants[].rank: Best-of-N signals — recommended flags the agent’s top pick; rank orders the variants. These plus variant_axis and keep_mode are how best-of-N is expressed.
variants[].eval: Present only when the request supplied an advisory evaluator and the agent advertises creative.supports_evaluator. The rank-side of the get_creative_features feature oracle. eval.features[] is creative-feature-result[] — the same shape get_creative_features.results[] returns (e.g. a creative_quality_score number, an on_brief categorical, a calibrated predicted_performance); the wrapper is open, each feature item is closed. The agent runs a gate-then-rank pipeline over its best-of-N: it evaluates each leaf, drops leaves failing the hard evaluator.feature_requirement[] gate from its recommended survivors, then orders survivors by evaluator.rank_by ([{feature_id, direction}]) — which is what recommended/rank reflect. The gate is internal pruning of which leaves the agent recommends from its own exploration, not an AdCP-layer block: what is produced and billed is governed by max_variants/max_creatives/max_spend, so this block appears only on returned (billed) leaves. Feature discovery uses get_adcp_capabilities.governance.creative_features; evaluator_id is an account-scoped preset that emits values over that feature vocabulary, not a discovered feature ID and not a separate evaluator feature catalog. The exemplars form calibrates one predicted_performance feature in [0,1]; a pass/warn/fail verdict is a categorical string feature value gated via feature_requirement.allowed_values — eval.features[] is a feature measurement, never a stored verdict. When the evaluator names an external agent, it must be on the seller’s creative_policy.accepted_verifiers[] (off-list → EVALUATOR_AGENT_NOT_ACCEPTED); the producing agent authenticates its outbound call on the transport, not inside the evaluator payload. Sellers SHOULD populate eval.calls_used / eval.seconds_used when agent_url was used and an eval_budget was supplied.
variants[] pricing receipt: Each variant carries a per-leaf receipt (pricing_option_id, vendor_cost, currency, consumption) for the work that produced it. Whenever the build reports cost (the aggregate vendor_cost is present), every produced leaf MUST carry its own vendor_cost + currency (schema-enforced) — leaves are the billing source of truth, and an untrafficked leaf is reconciled from this receipt alone. A CPM-deferred leaf reports vendor_cost: 0.
items_total / items_returned: For catalog fan-out, the total eligible catalog items and how many creatives were returned (e.g. “5 of 150”).
leaves_total / leaves_returned: Leaf-granular counts — total leaves the request would produce vs. how many were actually produced/billed. When budget_status is capped, leaves_returned < leaves_total is the shortfall (works even for variant-only fan-out with no catalog).
vendor_cost / currency: Aggregate cost across all produced variants in the response.
keep_mode_applied: Echoes the keep_mode the agent applied (present when the request set it). keep_mode is advisory and doesn’t change what’s produced or billed, so this is your confirmation the hint was received — the audit trail for a “I asked for keep_one but was billed for N” dispute.
selection_strategy_applied: Echoes the selection_strategy the agent applied (when max_creatives sampling occurred). The ranking itself shows in rank/recommended on the leaves.
budget_status: complete (default; absent == complete) or capped — a max_spend ceiling stopped production early (a successful partial build, not a failure). See Spend controls.
errors[]: Advisory (non-terminal) entries on an otherwise-successful build — e.g. a BUDGET_CAP_REACHED notice when budget_status is capped.

You pay for every produced variant (per_unit × N), not just the ones you keep. Keeping is a separate client act of trafficking the chosen build_variant_id(s), typically by using each kept leaf as creative_id on sync_creatives. A kept variant lazily earns a creative record when it is added to the library or first trafficked; that creative_id is what flows to report_usage and delivery reporting. An unkept variant is still billed but never earns a creative_id.

Atomicity differs by axis. Variant production per format is atomic — if one variant for a format fails, that format’s build fails. Catalog fan-out (max_creatives, per item) is non-atomic: individual creatives[] entries may succeed while others fail. A failed item is returned as a creatives[] entry carrying errors[] (and no variants[]); the batch still succeeds.Build-time variants are not delivery variants. The build_variant_id here is a pre-delivery handle for an alternative you produced. It is a different namespace from the served variant_id in get_creative_delivery, which identifies a creative execution that was delivered. A build-time variant becomes a delivery variant only once you keep and traffic it.Resolutions and quality tiers are not variants. Multiple sizes or quality levels belong on the format axis — pass them as target_format_ids (or quality), not as variant_axis values. Variants are alternatives for the same format (different voice, theme, or best-of-N take).

Conversational refinement re-builds a prior variant with free-form direction — “make it warmer”, “tighten the CTA”. The typed config surface is closed by design, so free-form intent rides the open surface that already exists: the message field (whose description is already “For refinement, this describes the desired changes”). Refinement is therefore not a new task — it’s build_creative with one extra input:

Pass refine_from_build_variant_id (a prior leaf’s build_variant_id) plus your instruction in message and any config delta.
The agent re-builds from that leaf and returns new variants, each with parent_build_variant_id set to the source. A refinement is never a mutation — the parent leaf is unchanged, and the new leaf earns its own build_variant_id (and, on trafficking, its own creative_id).
transformer_id and the target format(s) are inherited from the parent; you don’t repeat them. Passing a transformer_id or target format that differs from the parent’s is an INVALID_REQUEST. config is applied as a delta over the parent’s config.
Composes with max_variants / variant_axis (e.g. “three warmer takes” → three refined leaves), but not with max_creatives / catalog fan-out — you refine one produced creative, not a catalog.
Requires the agent to advertise creative.supports_refinement: true (it retains produced leaves for an agent-defined window). Agents that retain nothing return UNSUPPORTED_FEATURE; refine a buyer-held manifest instead via the transform path (creative_manifest + message). An unknown or no-longer-retained ref returns REFERENCE_NOT_FOUND with error.field set to refine_from_build_variant_id.

Any build can be refined, not just variant builds: a single-format BuildCreativeSuccess carries an optional build_variant_id (present when the agent supports refinement) that you pass as refine_from_build_variant_id. Multi-format builds that need per-output refinable leaves should request the variant shape (max_variants), since the bare creative_manifests[] array carries no leaf ids. AI-derivative attribution rides the manifest’s existing provenance; parent_build_variant_id carries only the lineage edge (refinements chain into a tree).

test=false

{
  "refine_from_build_variant_id": "bv_card01_a",
  "message": "Warmer lighting, and move the logo to the lower-right.",
  "max_variants": 3,
  "account": { "account_id": "acct_acme" },
  "idempotency_key": "7f2a1b3c-4d5e-6f70-8192-a3b4c5d6e7f8"
}

Spend controls

Fan-out and refinement can produce many independently-billed leaves (max_creatives × max_variants), and per_unit pricing gives a rate but not the unit count in advance (a 6-second voiceover and a 60-second one cost 10× at the same rate). Two opt-in controls, both gated by creative.supports_spend_controls:

Estimate first (mode: "estimate"). A dry run: the agent produces and bills nothing and returns a BuildCreativeEstimate with a cost_low/cost_high band (and basis: fixed = exact, estimated_units = generative projection, cpm_deferred = cost accrues at serve). The band is the load-bearing piece — the seller derives it from your actual inputs, so you don’t have to guess unit counts.
Cap the call (max_spend: { amount, currency }). A hard stop: the agent produces leaves until the next would push aggregate vendor_cost over amount, then returns the partial BuildCreativeVariantSuccess with budget_status: "capped" and an advisory BUDGET_CAP_REACHED in errors[] — every returned leaf is real and billed, nothing produced is discarded. The leaf-granular shortfall is leaves_returned < leaves_total (not items_returned/items_total, which count catalog items and don’t capture a variant-only or mid-item cap); the BUDGET_CAP_REACHED advisory is the authoritative cap signal. If even the first leaf would exceed the cap, the call fails with a terminal BUDGET_CAP_REACHED. currency must match the rate card (no FX) or the request is rejected INVALID_REQUEST (error.field: max_spend.currency). max_spend bounds only build-time vendor_cost — CPM-priced builds (basis: cpm_deferred) are 0 at build time and accrue at serve, so the cap never engages; bound a CPM fan-out with max_creatives instead.

They compose: estimate to get cost_high, then execute with max_spend = cost_high × a safety margin (CPM builds excepted — their cost_high is 0 at build time). max_spend caps a single call; to bound an autonomous refinement loop, track aggregate vendor_cost across calls and stop issuing them (a buyer responsibility in this revision — a protocol-level session budget is deferred to the working group).

max_spend and mode: "estimate" require the agent to advertise creative.supports_spend_controls; otherwise they’re rejected with UNSUPPORTED_FEATURE. They’re only meaningful with bills_through_adcp: true (an out-of-band biller has no AdCP cost to cap against).

Estimate response

A mode: "estimate" request returns the BuildCreativeEstimate shape (oneOf member 4 of 6) — produced and billed nothing, just a projected cost band:

test=false

{
  "$schema": "/schemas/media-buy/build-creative-response.json",
  "status": "completed",
  "mode": "estimate",
  "estimate": {
    "items_total": 150,
    "items_to_produce": 5,
    "variants_per_item": 3,
    "leaves_total": 15,
    "currency": "USD",
    "cost_low": 6.00,
    "cost_high": 9.00,
    "cost_expected": 7.50,
    "basis": "estimated_units"
  },
  "expires_at": "2026-06-01T00:00:00Z"
}

estimate.leaves_total = items_to_produce × variants_per_item (× conditions_total when signal_conditions was sent) — the number of billable leaves mode: "execute" would produce.
estimate.cost_low / cost_high / cost_expected: the projected aggregate cost band. The seller derives it from your actual inputs.
estimate.basis: fixed (per-format flat — cost_low == cost_high, exact), estimated_units (generative per_unit; the band reflects unit-count uncertainty), or cpm_deferred (CPM — build-time cost 0, accrues at serve, so the band is 0).
estimate.per_leaf (optional): per-leaf breakdown.
Estimates are advisory / non-binding in this revision (binding quotes are deferred to the working group).

Field descriptions

creative_manifest: (single-format) The complete creative manifest ready for use with sync_creatives or preview_creative
creative_manifests: (multi-format) Array of complete creative manifests, one per requested format. Each contains its own format_id.
format_id: The target format (matches the requested format)
assets: Map of asset keys to asset content — includes creative content (images, text, URLs), catalogs, briefs, and anything else the format requires
expires_at: Optional ISO 8601 timestamp when generated asset URLs in the manifest expire. Set to the earliest expiration across all generated assets. Re-build the creative after this time to get fresh URLs. Not present when the manifest contains no expiring URLs (e.g., pure text generation or assembly-only transforms).
preview: Optional. Present when include_preview was true in the request and the agent supports inline preview. Contains the same content fields as a preview_creative single response (previews, interactive_url, expires_at) minus the response_type discriminator, so clients can reuse the same preview rendering logic. Preview URLs follow the same durability contract as preview_creative: they remain dereferenceable until expires_at, or until explicit out-of-band revocation when no expiration is present. For single-format responses, each entry in previews[] corresponds to an input set from preview_inputs. For multi-format responses, each entry includes a format_id and corresponds to one requested format (one default preview per format; preview_inputs is ignored).
preview_error: Optional. Standard error object (code, message, recovery) present when include_preview was true but preview generation failed. The recovery field indicates whether the failure is transient (retry later), correctable, or terminal. Distinguishes “agent doesn’t support inline preview” (field absent, no error) from “preview generation failed” (field present with structured error).

Compliance errors

If the manifest includes a brief asset with compliance requirements that the creative agent cannot satisfy, the agent MUST return an error — not a partial success. Unsatisfied disclosures are a hard failure.

{
  "$schema": "/schemas/media-buy/build-creative-response.json",
  "status": "failed",
  "errors": [
    {
      "code": "COMPLIANCE_UNSATISFIED",
      "message": "Required disclosure cannot be rendered in this format",
      "field": "creative_manifest.assets.brief.compliance.required_disclosures[0]",
      "details": {
        "disclosure_text": "Past performance is not indicative of future results.",
        "position": "footer",
        "reason": "Format display_mobile_320x50 does not support footer position"
      },
      "suggestion": "Use a format that supports footer disclosures, or change position to 'overlay'"
    }
  ]
}

Creative agents MUST validate that all required_disclosures can be satisfied in the target format before generating the creative. If any disclosure cannot be placed as specified, the entire request fails. This ensures regulated creatives are never served without required legal text.

Response timing

How the creative agent responds depends on how long the operation will take:

Expected duration	Status	Caller experience
Under 30 seconds	`completed`	Result returned directly — synchronous
Over 30 seconds, server actively processing	`working`	Out-of-band status updates while the server continues processing. Caller holds the connection — still synchronous from their perspective
Blocked on external dependency (human review, approval)	`submitted`	Truly async — caller should configure a webhook via `push_notification_config` and move on

The creative agent decides which path to take based on the work involved. Library retrieval is instant. Simple transformations take seconds. AI generation varies — a quick banner might complete in 10 seconds, a complex video composition might take minutes.

`working` is a progress signal, not a polling trigger

When the server expects to take more than 30 seconds but is actively processing, it sends working as an out-of-band MCP status update. This keeps the client informed (“I’m on it”) without requiring the caller to switch to a polling or webhook pattern. The connection stays open and the result arrives when it’s ready.

When to go async

submitted means the operation is blocked on something outside the server’s control:

Human creative review — brand guidelines require approval before returning
External approval workflows — third-party compliance or legal review

For these cases, configure a webhook via push_notification_config to receive the result. See Async Operations and Push Notifications.

Human-in-the-loop

The agent may return status: "input-required" when it needs human input — for example, when brand guidelines require creative approval or when the agent needs clarification on creative direction:

{
  "reason": "CREATIVE_DIRECTION_NEEDED"
}

Reason codes:

APPROVAL_REQUIRED — Creative needs human approval before finalizing
CREATIVE_DIRECTION_NEEDED — Agent needs clarification on creative brief or direction
ASSET_SELECTION_NEEDED — Agent needs the caller to choose between asset options

Workflow integration

Typical generation workflow

Build: Use build_creative to generate/transform the manifest
Preview: Use preview_creative to see how it renders (see preview_creative)
Sync: Use sync_creatives to traffic the finalized creative

You can combine steps 1 and 2 by setting include_preview: true on the build request. If the agent supports it, the response includes a preview object alongside the manifest — same content fields as preview_creative, no extra round trip. If the agent doesn’t support inline preview, the field is simply absent and you fall back to a separate preview_creative call. Always check for the presence of preview rather than assuming it will be there when requested. Use preview_quality to control render fidelity independently from build quality. For example, build at quality: "draft" (fast concept generation) but preview at preview_quality: "production" (full-fidelity render to show stakeholders the layout). If preview_quality is omitted, the agent uses its own default.

// Build at draft quality, but preview at production quality for stakeholder review
{
  "message": "Create a display banner for our winter sale",
  "target_format_id": {"agent_url": "...", "id": "display_300x250_generative"},
  "brand": { "domain": "mybrand.com" },
  "quality": "draft",
  "include_preview": true,
  "preview_quality": "production",
  "creative_manifest": {
    "format_id": {"agent_url": "...", "id": "display_300x250_generative"},
    "assets": {
      "product_catalog": {
        "type": "product",
        "catalog_id": "winter-products"
      }
    }
  }
}

// Or: Build first, preview separately
// Step 1: Build
{
  "message": "Create a display banner for our winter sale",
  "target_format_id": {"agent_url": "...", "id": "display_300x250_generative"},
  "brand": { "domain": "mybrand.com" },
  "creative_manifest": {
    "format_id": {"agent_url": "...", "id": "display_300x250_generative"},
    "assets": {
      "product_catalog": {
        "type": "product",
        "catalog_id": "winter-products"
      }
    }
  }
}

// Step 2: Preview (using the output manifest from step 1)
{
  "request_type": "single",
  "format_id": {"agent_url": "...", "id": "display_300x250"},
  "creative_manifest": {
    /* output from build_creative - includes all assets */
  },
  "inputs": [{"name": "Desktop view"}, {"name": "Mobile view"}]
}

// Step 3: Sync (if preview looks good)
{
  "creative_manifests": [{ /* approved manifest from build_creative */ }]
}

Key insight: The manifest carries everything. Briefs, catalogs, images, text — all live in the assets map and flow through from input to output. No need to pass them separately at each step.

Examples

Example 1: Pure generation (generative format)

Generate a creative from scratch using a generative format:

{
  "$schema": "/schemas/media-buy/build-creative-request.json",
  "idempotency_key": "f6a7b8c9-d0e1-4234-f567-89abcdef0123",
  "message": "Create a display banner for our winter sale. Use warm colors and emphasize the 50% discount",
  "target_format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_300x250_generative"
  },
  "brand": {
    "domain": "mybrand.com"
  },
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_300x250_generative"
    },
    "assets": {
      "offering_catalog": {
        "asset_type": "catalog",
        "type": "offering",
        "items": [
          {
            "offering_id": "winter-sale",
            "name": "Winter Sale Collection",
            "description": "50% off all winter items"
          }
        ]
      }
    }
  }
}

Response:

{
  "$schema": "/schemas/media-buy/build-creative-response.json",
  "status": "completed",
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_300x250"
    },
    "assets": {
      "offering_catalog": {
        "asset_type": "catalog",
        "type": "offering",
        "catalog_id": "winter-sale"
      },
      "banner_image": {
        "asset_type": "image",
        "url": "https://cdn.creative-agent.com/generated/banner_12345.png",
        "width": 300,
        "height": 250
      },
      "clickthrough_url": {
        "asset_type": "url",
        "url": "https://mybrand.example.com/winter-sale?campaign={MEDIA_BUY_ID}"
      }
    }
  }
}

Example 2: Format transformation

Transform an existing 728x90 leaderboard to a 300x250 banner:

{
  "$schema": "/schemas/media-buy/build-creative-request.json",
  "idempotency_key": "a7b8c9d0-e1f2-4345-a678-9abcdef01234",
  "message": "Adapt this leaderboard creative to a 300x250 banner format",
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_728x90"
    },
    "assets": {
      "banner_image": {
        "asset_type": "image",
        "url": "https://cdn.mybrand.com/leaderboard.png",
        "width": 728,
        "height": 90
      },
      "headline": {
        "asset_type": "text",
        "content": "Spring Sale - 30% Off Everything"
      },
      "clickthrough_url": {
        "asset_type": "url",
        "url": "https://mybrand.example.com/spring?campaign={MEDIA_BUY_ID}"
      }
    }
  },
  "target_format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_300x250"
  }
}

Response:

{
  "$schema": "/schemas/media-buy/build-creative-response.json",
  "status": "completed",
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_300x250"
    },
    "assets": {
      "banner_image": {
        "asset_type": "image",
        "url": "https://cdn.creative-agent.com/resized/banner_67890.png",
        "width": 300,
        "height": 250
      },
      "headline": {
        "asset_type": "text",
        "content": "Spring Sale - 30% Off"
      },
      "clickthrough_url": {
        "asset_type": "url",
        "url": "https://mybrand.example.com/spring?campaign={MEDIA_BUY_ID}"
      }
    }
  }
}

Example 3: Transformation with specific instructions

Adapt a creative for mobile with specific design changes:

{
  "$schema": "/schemas/media-buy/build-creative-request.json",
  "idempotency_key": "b8c9d0e1-f2a3-4456-b789-abcdef012345",
  "message": "Make this mobile-friendly: increase text size, simplify the layout, and make the CTA button more prominent",
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_300x600"
    },
    "assets": {
      "background_image": {
        "asset_type": "image",
        "url": "https://cdn.mybrand.com/bg.jpg",
        "width": 300,
        "height": 600
      },
      "headline": {
        "asset_type": "text",
        "content": "Discover Our New Collection"
      },
      "body_text": {
        "asset_type": "text",
        "content": "Shop the latest styles with free shipping on orders over $50"
      },
      "cta_text": {
        "asset_type": "text",
        "content": "Shop Now"
      }
    }
  },
  "target_format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_mobile_320x50"
  }
}

Response:

{
  "$schema": "/schemas/media-buy/build-creative-response.json",
  "status": "completed",
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_mobile_320x50"
    },
    "assets": {
      "banner_image": {
        "asset_type": "image",
        "url": "https://cdn.creative-agent.com/mobile/banner_mobile_123.png",
        "width": 320,
        "height": 50
      },
      "headline": {
        "asset_type": "text",
        "content": "New Collection - Shop Now"
      },
      "clickthrough_url": {
        "asset_type": "url",
        "url": "https://mybrand.example.com/new?campaign={MEDIA_BUY_ID}"
      }
    }
  }
}

Example 4: Generation with creative brief

Generate a creative using structured campaign context via brand and a brief asset on the manifest:

{
  "$schema": "/schemas/media-buy/build-creative-request.json",
  "idempotency_key": "c9d0e1f2-a3b4-4567-c890-bcdef0123456",
  "message": "Create a display banner for the holiday campaign targeting gift shoppers",
  "target_format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_300x250_generative"
  },
  "brand": {
    "domain": "acmecorp.com"
  },
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_300x250_generative"
    },
    "assets": {
      "brief": {
        "asset_type": "brief",
        "name": "Holiday Sale 2025",
        "objective": "conversion",
        "audience": "Holiday gift shoppers aged 25-55",
        "territory": "festive savings",
        "messaging": {
          "headline": "Holiday Deals Are Here",
          "cta": "Shop Now",
          "key_messages": [
            "Up to 50% off select items",
            "Free shipping on orders over $50"
          ]
        },
        "reference_assets": [
          {
            "url": "https://cdn.acmecorp.com/holiday-mood-board.pdf",
            "role": "mood_board",
            "description": "Holiday campaign mood board with festive color palette"
          }
        ]
      },
      "offering_catalog": {
        "asset_type": "catalog",
        "type": "offering",
        "items": [
          {
            "offering_id": "holiday-sale",
            "name": "Holiday Sale Collection",
            "description": "Up to 50% off select holiday items"
          }
        ]
      }
    }
  }
}

Example 5: Generation with compliance requirements

Generate a financial services creative with regulatory disclosures and prohibited claims:

{
  "$schema": "/schemas/media-buy/build-creative-request.json",
  "idempotency_key": "d0e1f2a3-b4c5-4678-d901-cdef01234567",
  "message": "Create a display banner promoting retirement planning advisory services",
  "target_format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_300x250_generative"
  },
  "brand": {
    "domain": "pinnaclewealth.com"
  },
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_300x250_generative"
    },
    "assets": {
      "brief": {
        "asset_type": "brief",
        "name": "Retirement Advisory Q1 2026",
        "objective": "consideration",
        "audience": "Pre-retirees aged 50-65 with investable assets",
        "territory": "trusted financial guidance",
        "messaging": {
          "headline": "Plan Your Retirement with Confidence",
          "cta": "Schedule a Consultation",
          "key_messages": [
            "Personalized retirement planning",
            "Tax-efficient investment strategies"
          ]
        },
        "compliance": {
          "required_disclosures": [
            {
              "text": "Past performance is not indicative of future results.",
              "position": "footer",
              "jurisdictions": ["US"],
              "regulation": "SEC Rule 156"
            },
            {
              "text": "Securities offered through Pinnacle Wealth Securities, LLC. Member FINRA/SIPC.",
              "position": "footer",
              "jurisdictions": ["US"],
              "regulation": "FINRA Rule 2210"
            },
            {
              "text": "Capital at risk. The value of investments can go down as well as up.",
              "position": "prominent",
              "jurisdictions": ["GB"],
              "regulation": "FCA COBS 4.5"
            },
            {
              "text": "Pinnacle Wealth Advisors is a registered investment adviser.",
              "position": "footer"
            }
          ],
          "prohibited_claims": [
            "guaranteed returns",
            "risk-free investment",
            "outperform the market"
          ]
        }
      }
    }
  }
}

Compliance requirements differ by jurisdiction: the US requires SEC-mandated disclosures while the UK requires FCA-mandated risk warnings. The third disclosure (no jurisdictions) applies globally. The prohibited_claims array tells the creative agent which claims to avoid in generated copy.

Example 6: Commerce media with brief and product catalog

Generate a sponsored product carousel with campaign context, compliance disclosures, and a synced product catalog:

{
  "$schema": "/schemas/media-buy/build-creative-request.json",
  "idempotency_key": "e1f2a3b4-c5d6-4789-e012-def012345678",
  "message": "Create a product carousel highlighting the top 4 sale items",
  "target_format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "sponsored_product_carousel"
  },
  "brand": {
    "domain": "novabrands.com"
  },
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "sponsored_product_carousel"
    },
    "assets": {
      "brief": {
        "asset_type": "brief",
        "name": "Spring Sale 2026",
        "objective": "conversion",
        "audience": "Value-conscious shoppers aged 25-45",
        "messaging": {
          "headline": "Spring Sale — Up to 40% Off",
          "cta": "Shop Now"
        },
        "compliance": {
          "required_disclosures": [
            {
              "text": "Sponsored",
              "position": "prominent"
            },
            {
              "text": "Prices may vary by location. See store for details.",
              "position": "footer"
            }
          ]
        }
      },
      "product_catalog": {
        "asset_type": "catalog",
        "type": "product",
        "catalog_id": "spring_sale_2026"
      }
    }
  }
}

The brief and product catalog travel together in the manifest’s assets map. The format declares both a brief and catalog asset type — the buying agent discovers this via list_creative_formats and syncs the required catalog before submitting.

Example 7: Build with inline preview

Build a creative and get preview renders in the same response:

{
  "$schema": "/schemas/media-buy/build-creative-request.json",
  "idempotency_key": "f2a3b4c5-d6e7-4890-f123-ef0123456789",
  "message": "Create a banner for our spring campaign",
  "target_format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_300x250_generative"
  },
  "brand": {
    "domain": "novabrands.com"
  },
  "include_preview": true,
  "preview_inputs": [
    { "name": "Default" },
    { "name": "Dark mode", "macros": { "COLOR_SCHEME": "dark" } }
  ],
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_300x250_generative"
    },
    "assets": {
      "offering_catalog": {
        "asset_type": "catalog",
        "type": "offering",
        "items": [
          {
            "offering_id": "spring-promo",
            "name": "Spring Collection",
            "description": "30% off new arrivals"
          }
        ]
      }
    }
  }
}

Response (when the agent supports inline preview):

{
  "$schema": "/schemas/media-buy/build-creative-response.json",
  "status": "completed",
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_300x250"
    },
    "assets": {
      "offering_catalog": {
        "asset_type": "catalog",
        "type": "offering",
        "catalog_id": "spring-promo"
      },
      "banner_image": {
        "asset_type": "image",
        "url": "https://cdn.creative-agent.com/generated/spring_abc123.png",
        "width": 300,
        "height": 250
      },
      "clickthrough_url": {
        "asset_type": "url",
        "url": "https://novabrands.com/spring"
      }
    }
  },
  "preview": {
    "previews": [
      {
        "preview_id": "prev_default",
        "renders": [
          {
            "render_id": "r1",
            "output_format": "url",
            "preview_url": "https://preview.creative-agent.com/abc123/default",
            "role": "primary",
            "dimensions": { "width": 300, "height": 250 }
          }
        ],
        "input": { "name": "Default" }
      },
      {
        "preview_id": "prev_dark",
        "renders": [
          {
            "render_id": "r2",
            "output_format": "url",
            "preview_url": "https://preview.creative-agent.com/abc123/dark",
            "role": "primary",
            "dimensions": { "width": 300, "height": 250 }
          }
        ],
        "input": { "name": "Dark mode", "macros": { "COLOR_SCHEME": "dark" } }
      }
    ],
    "expires_at": "2026-03-13T06:00:00Z"
  },
  "expires_at": "2026-03-13T06:00:00Z"
}

The preview object contains the same content fields as a preview_creative single response (previews, interactive_url, expires_at). If the agent does not support inline preview, this field is absent — the buyer agent falls back to a separate preview_creative call. If preview generation fails, the response includes preview_error with a standard error object (code, message, recovery) instead.

Example 8: Draft generation with item limit

Generate a draft-quality creative from a large catalog, capping the number of items:

{
  "$schema": "/schemas/media-buy/build-creative-request.json",
  "idempotency_key": "a3b4c5d6-e7f8-4901-a234-f01234567890",
  "message": "Create hero images for our top sale items",
  "target_format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "sponsored_product_carousel"
  },
  "brand": {
    "domain": "novabrands.com"
  },
  "quality": "draft",
  "item_limit": 4,
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "sponsored_product_carousel"
    },
    "assets": {
      "product_catalog": {
        "asset_type": "catalog",
        "type": "product",
        "catalog_id": "spring_sale_2026"
      }
    }
  }
}

The catalog may contain hundreds of products, but item_limit: 4 ensures only 4 hero images are generated. quality: "draft" produces fast, lower-fidelity output for review. Response:

{
  "$schema": "/schemas/media-buy/build-creative-response.json",
  "status": "completed",
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "sponsored_product_carousel"
    },
    "assets": {
      "product_catalog": {
        "asset_type": "catalog",
        "type": "product",
        "catalog_id": "spring_sale_2026"
      },
      "card_1_image": {
        "asset_type": "image",
        "url": "https://cdn.creative-agent.com/draft/card1_abc123.jpg",
        "width": 400,
        "height": 400
      },
      "card_2_image": {
        "asset_type": "image",
        "url": "https://cdn.creative-agent.com/draft/card2_def456.jpg",
        "width": 400,
        "height": 400
      },
      "card_3_image": {
        "asset_type": "image",
        "url": "https://cdn.creative-agent.com/draft/card3_ghi789.jpg",
        "width": 400,
        "height": 400
      },
      "card_4_image": {
        "asset_type": "image",
        "url": "https://cdn.creative-agent.com/draft/card4_jkl012.jpg",
        "width": 400,
        "height": 400
      }
    }
  },
  "expires_at": "2026-03-02T06:00:00Z"
}

The expires_at field signals when the generated CDN URLs expire. Re-build after this time to get fresh URLs. Once the direction is approved, re-submit the output manifest with quality: "production" for final renders.

Key concepts

Brand vs creative brief

	Brand	Creative Brief
Scope	Brand identity	Campaign context
Lifespan	Stable across campaigns	Specific to a campaign or flight
Contains	Colors, logos, fonts, tone	Audience, territory, messaging, compliance, reference assets
Legal	Brand-level disclaimers (always-on)	Campaign-specific regulatory disclosures (regional, product-based)
Source	Brand registry / `/.well-known/brand.json`	Agency or brand team
Lives on	Resolved via domain lookup	The manifest’s assets map (`assets.brief`)

Both are optional. brand provides stable brand identity (colors, logos, tone) resolved via the domain’s /.well-known/brand.json. The brief is an asset on the manifest (assets.brief), so it travels with the creative through regeneration, resizing, and auditing. The message field provides per-request natural language instructions. Precedence: The brand parameter is the authoritative source for creative rendering context (colors, logos, tone). Layering: The brief asset on the manifest provides structured direction; message on the request provides per-request natural language overrides. When both provide conflicting direction, message takes precedence as the most specific instruction.

Transformation model

build_creative follows a manifest-in, manifest-out model:

Input: Creative manifest (can be minimal or complete — everything lives in assets)
Process: Transform/generate based on message and manifest content
Output: Target creative manifest ready for preview or sync (brief carries forward)

Pure generation vs transformation

Pure Generation: Provide minimal creative_manifest with just the format_id, catalog assets (if the format renders catalog items), and any required seed assets. The creative agent generates output assets from scratch using message as guidance.
Transformation: Provide complete creative_manifest with all existing assets. The creative agent adapts existing assets to the target format, optionally following guidance in message.

Integration with other tasks

build_creative → Generates manifest (optionally with inline preview via include_preview)
preview_creative → Renders the manifest separately (see preview_creative)
sync_creatives → Traffics the finalized manifest

Use include_preview: true to combine build and preview into one call. If the agent doesn’t support it, the response simply omits the preview field — fall back to a separate preview_creative call. Either way, the preview content fields (previews, interactive_url, expires_at) are the same. This separation allows you to:

Build once, preview multiple times with different contexts
Iterate on build without re-syncing
Preview before committing to traffic

build_creative supports multi-turn iteration without a mode flag. The presence and combination of fields determines the operation:

Generation: message + minimal creative_manifest (empty or seed assets) + target_format_id
Transformation: full creative_manifest + message + target_format_id
Library retrieval: creative_id + target_format_id + optional macro_values
Refinement: previous output as creative_manifest + message with changes

To refine, pass the previous response’s creative_manifest back as input with a new message. Alternatively, update the brief asset (assets.brief) to change the creative direction — the brief is the buyer-owned source of truth for what the creative should be.

{
  "$schema": "/schemas/media-buy/build-creative-request.json",
  "idempotency_key": "b4c5d6e7-f8a9-4012-b345-012345678901",
  "message": "Make the headline bolder and increase the contrast on the CTA button",
  "target_format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_300x250_generative"
  },
  "creative_manifest": {
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_300x250"
    },
    "assets": {
      "banner_image": {
        "asset_type": "image",
        "url": "https://cdn.creative-agent.com/generated/banner_12345.png",
        "width": 300,
        "height": 250
      },
      "headline": {
        "asset_type": "text",
        "content": "50% Off Winter Sale"
      },
      "clickthrough_url": {
        "asset_type": "url",
        "url": "https://mybrand.example.com/winter-sale?campaign={MEDIA_BUY_ID}"
      }
    }
  }
}

Error codes

Code	Description
`FORMAT_NOT_SUPPORTED`	The `target_format_id` (or `target_format_ids[N]` in a multi-format request) is not supported by this creative agent. For canonical creative-agent routing, retry with an advertised `creative.supported_formats[].capability_id`; legacy named-format IDs remain valid when the agent still advertises them.
`INVALID_MANIFEST`	The `creative_manifest` is malformed or missing required assets for the target format
`CREATIVE_NOT_FOUND`	The `creative_id` does not exist in the agent’s library (or in the specified `concept_id`)
`COMPLIANCE_UNSATISFIED`	A required disclosure from the brief cannot be rendered in the target format (e.g., format does not support the required disclosure position)

​Request parameters

​Pricing response fields

​Recipe identity

​Evaluator authentication

​Generation controls

​Use cases

​Pure generation (creating from scratch)

​Transformation (adapting existing creative)

​Format resizing

​Library retrieval

​Multi-format generation

​Multi-format workflow

​Transformers & variants

​Paid build with pricing

​Response format

​Single-format response

​Multi-format response

​Variant response

​Refinement

​Spend controls

​Estimate response

​Field descriptions

​Compliance errors

​Response timing

​working is a progress signal, not a polling trigger

​When to go async

​Human-in-the-loop

​Workflow integration

​Typical generation workflow

​Examples

​Example 1: Pure generation (generative format)

​Example 2: Format transformation

​Example 3: Transformation with specific instructions

​Example 4: Generation with creative brief

​Example 5: Generation with compliance requirements

​Example 6: Commerce media with brief and product catalog

​Example 7: Build with inline preview

​Example 8: Draft generation with item limit

​Key concepts

​Brand vs creative brief

​Transformation model

​Pure generation vs transformation

​Integration with other tasks

​Iterative refinement

​Error codes

Request parameters

Pricing response fields

Recipe identity

Evaluator authentication

Generation controls

Use cases

Pure generation (creating from scratch)

Transformation (adapting existing creative)

Format resizing

Library retrieval

Multi-format generation

Multi-format workflow

Transformers & variants

Paid build with pricing

Response format

Single-format response

Multi-format response

Variant response

Refinement

Spend controls

Estimate response

Field descriptions

Compliance errors

Response timing

`working` is a progress signal, not a polling trigger

When to go async

Human-in-the-loop

Workflow integration

Typical generation workflow

Examples

Example 1: Pure generation (generative format)

Example 2: Format transformation

Example 3: Transformation with specific instructions

Example 4: Generation with creative brief

Example 5: Generation with compliance requirements

Example 6: Commerce media with brief and product catalog

Example 7: Build with inline preview

Example 8: Draft generation with item limit

Key concepts

Brand vs creative brief

Transformation model

Pure generation vs transformation

Integration with other tasks

Iterative refinement

Error codes