Optionaladcp_version?: stringRelease-precision AdCP version (VERSION.RELEASE, e.g. "3.0", "3.1", "3.1-beta"). On a request: the buyer's release pin — the seller validates against its supported_versions and returns VERSION_UNSUPPORTED on cross-major mismatch, or downshifts to the highest supported release within the same major. On a response: the release the seller actually served — clients SHOULD validate the response against that release's schema, not against their pin. Patches are not negotiated; surface them as build_version on capabilities for operational visibility. When omitted, falls back to adcp_major_version (deprecated) or server default. Buyers SHOULD emit both adcp_version and adcp_major_version through 3.x to remain compatible with sellers that only read the legacy field. NORMALIZATION: SDKs that read full-semver values from bundle metadata (e.g. ComplianceIndex.published_version = "3.1.0-beta.1") MUST normalize to release-precision ("3.1-beta.1") before emitting on the wire — meta-field values are NOT valid wire values.
Optionaladcp_major_version?: numberDEPRECATED in favor of adcp_version (release-precision string). Servers MUST continue to honor this field through 3.x. Removed in 4.0. Original semantics: the AdCP major version the buyer's payloads conform to. Sellers validate against their supported major_versions and return VERSION_UNSUPPORTED if unsupported. When omitted, the seller assumes its highest supported version.
Optionalmessage?: stringNatural language instructions for the transformation or generation. For pure generation, this is the creative brief. For transformation, this provides guidance on how to adapt the creative. For refinement, this describes the desired changes.
Optionalcreative_manifest?: CreativeManifestOptionalcreative_id?: stringReference 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.
Optionalconcept_id?: stringCreative concept containing the creative. Creative agents SHOULD assign globally unique creative_id values; when they cannot guarantee uniqueness, concept_id is REQUIRED to disambiguate.
Optionalmedia_buy_id?: stringMedia buy identifier for tag generation context. When the creative agent is also the ad server, this provides the trafficking context needed to generate placement-specific tags (e.g., CM360 placement ID). Not needed when tags are generated at the creative level (most creative platforms).
Optionalpackage_id?: stringPackage identifier within the media buy. Used with media_buy_id when the creative agent needs line-item-level context for tag generation. Omit to get a tag not scoped to a specific package.
Optionaltarget_format_id?: FormatReferenceStructuredObjectOptionaltarget_format_ids?: FormatReferenceStructuredObject[]Array of format IDs to generate in a single call. Mutually exclusive with target_format_id. The creative agent produces one manifest per format. Each format definition specifies its own required input assets and output structure.
Optionaltransformer_id?: stringSelects an account-scoped transformer (discovered via list_transformers) to perform the build. One transformer per call. When present, the build uses this transformer and target_format_id/target_format_ids select which of its outputs to produce — they MUST be a subset of the transformer's output_format_ids. Render configuration goes in config.
Optionalconfig?: {}Typed render configuration for the selected transformer, keyed by each param's field (from the transformer's params[] in list_transformers). Example: { "voice": "isaac", "speaking_rate": 1.1, "mastering_preset": "podcast" }. The agent MUST validate config against the transformer's live params for this account and reject unrecognized keys and out-of-range / non-enumerated values with a field-attributed error (e.g. config.voice) rather than silently ignoring them — config drives a paid render. Genuinely vendor-specific or experimental knobs not declared as params belong in ext, not here. (The schema leaves this object open because legal keys are dynamic per transformer; strict validation is a normative agent obligation.) When refine_from_build_variant_id is set, config is applied as a DELTA over the parent leaf's config.
Optionalrefine_from_build_variant_id?: stringRefine a previously produced variant: re-build from the referenced build_variant_id, applying the natural-language instruction in message and any config delta, and return NEW lineage-linked variant(s) — each with parent_build_variant_id set to this id. A refinement is never a mutation; the parent leaf is unchanged. The transformer_id and target format(s) are inherited from the parent and need not be repeated; passing a transformer_id or target_format_id/target_format_ids that differs from the parent's is rejected with INVALID_REQUEST. Composes with max_variants / variant_axis (produces N refined alternatives), but is mutually exclusive with max_creatives / catalog fan-out (you refine one prior creative, not a catalog). Requires the agent to advertise creative.supports_refinement: true in get_adcp_capabilities; agents that do not retain prior builds reject with UNSUPPORTED_FEATURE. A ref that is unknown or no longer retained (agents retain produced leaves for an agent-defined window) is rejected with REFERENCE_NOT_FOUND, with error.field set to refine_from_build_variant_id. To refine a buyer-held manifest when the agent retains nothing, use the transform path instead (creative_manifest + message).
Optionalmode?: "execute" | "estimate"execute (default) produces and bills the creative(s). estimate is a DRY RUN: the agent produces nothing and bills nothing, and returns a BuildCreativeEstimate with a projected cost band (cost_low/cost_high) computed against THIS request's actual inputs (script length, brief, catalog size, max_creatives × max_variants) — the band the buyer cannot derive itself, since per_unit gives the rate but not the unit count. Requires the agent to advertise creative.supports_spend_controls; otherwise rejected with UNSUPPORTED_FEATURE.
Optionalmax_spend?: { amount: number; currency: string }Hard per-call spend ceiling. The agent produces leaves until the NEXT leaf would push the run's aggregate vendor_cost over amount, then STOPS and returns the partial BuildCreativeVariantSuccess produced so far with budget_status: "capped" (every returned leaf is real, trafficable, and billed — nothing produced is discarded; the leaf shortfall is leaves_returned < leaves_total). If even the first leaf would exceed the cap, the call fails with BUDGET_CAP_REACHED. currency MUST match the rate card's currency (the agent does not FX-convert) or the request is rejected with INVALID_REQUEST (error.field max_spend.currency). Requires creative.supports_spend_controls. Caps a SINGLE call — to bound a refinement loop, track aggregate vendor_cost across calls and stop issuing them (buyer responsibility in this revision). max_spend bounds only build-time vendor_cost: CPM-priced builds (estimate basis cpm_deferred) have build-time vendor_cost 0 and accrue at serve time, so max_spend never engages for them — bound a CPM fan-out with max_creatives instead.
Maximum aggregate vendor_cost to incur on this call, in currency.
ISO 4217 currency; MUST match the rate card.
Optionalmax_creatives?: numberCaps how many DISTINCT creatives to produce along the catalog/item fan-out axis — one creative per catalog item. Use it to sample a large catalog (e.g. send 150 job openings, set max_creatives: 5 to preview five). Distinct from item_limit, which caps how many catalog items a SINGLE creative consumes (DCO-style). Omitted with a catalog input means one creative per item up to the catalog/format bound; omitted without a catalog collapses to a single creative. Large fan-outs may return asynchronously. Mutually exclusive with refine_from_build_variant_id (refinement targets one prior creative, not a catalog fan-out). Supported only when the agent advertises creative.multiplicity.supports_catalog_fanout; values above max_creatives_limit are clamped. Pair with max_spend to bound the bill of a large fan-out.
Optionalsignal_conditions?: (SignalTargeting & { signal_agent_segment_id?: string })[]Advisory keep-all PRODUCTION axis: produce one distinct creative group per signal condition, each kept and trafficked with its own signal targeting (e.g. a rain creative AND a sun creative). Sibling to max_creatives (catalog axis), NOT a variant_axis value (which is choose-among). Each item reuses SignalTargeting (value_type-discriminated binary/categorical/numeric over signal_ref) so the produced group's signal_condition resolves condition identity through the SAME schema the sales-side package targeting uses, plus an optional signal_agent_segment_id carrying the RESOLVED-segment identity (vs signal_ref's definition identity) — echo a provider-exposed handle verbatim; it is the primary trafficking-compatibility key, with categorical signal_ref+value as the weaker fallback. Per #5280 this is an ADVISORY context pointer — it informs production and MUST NOT hard-block at the build_creative layer; trafficking-compatibility (a sun creative MUST NOT serve into rain-targeted packages) is enforced reject-at-trafficking on the sales side (SIGNAL_TARGETING_INCOMPATIBLE), not here. Triggers the BuildCreativeVariantSuccess shape. Supported only when the agent advertises creative.multiplicity.supports_signal_fanout; condition counts above max_signal_conditions_limit are CLAMPED (not rejected), consistent with max_creatives. Composes with max_creatives (catalog × conditions cross-product) and max_variants (variants per group).
Optionalmax_variants?: numberCaps how many ALTERNATIVES to produce per creative (different voices, themes, best-of-N, etc.). Default 1 preserves single-output behavior. Each variant is a real, independently-billed build (you pay for all produced); the buyer keeps one or many. When variant_axis.values[] is provided, its length is authoritative over max_variants. Resolutions/quality tiers are NOT variants — request them as additional target formats.
Optionalvariant_axis?: {Declares the dimension along which variants differ. When values is provided, the agent produces exactly one variant per value (e.g. an A/B of two voices). When only dimension is provided, the agent chooses up to max_variants variants along that dimension (e.g. best-of-N, themes).
What varies across variants. transformer_config varies a named config param (name it in field); best_of_n lets the agent explore and rank; custom is agent-defined (describe in label).
Optionalfield?: stringThe transformer config param field this axis sweeps. REQUIRED when dimension is transformer_config; values[] are then interpreted as values for config[field]. Omit for other dimensions.
Optionalvalues?: unknown[]Caller-fixed set of values for the axis (e.g. ["isaac", "sara"] for dimension voice). When present, len(values) is the variant count and is authoritative over max_variants.
Optionallabel?: stringHuman-readable description of the axis, especially for custom.
Optionalkeep_mode?: "keep_all" | "keep_one" | "keep_some"Advisory hint for how the buyer intends to use the variants. keep_one (best-of-N) and keep_some signal the agent to set recommended/rank on returned variants. Advisory only — it does not change what is returned or billed; every produced variant is returned and charged. Keeping is a client act of trafficking the chosen build_variant_id(s).
Optionalselection_strategy?: CreativeSelectionStrategyOptionalaccount?: AccountReferenceOptionalbrand?: BrandReferenceOptionalquality?: CreativeQualityOptionalevaluator?: EvaluatorSpecOptionalitem_limit?: numberMaximum number of catalog items a SINGLE creative consumes when generating (DCO-style — e.g. how many items fill one carousel/feed creative). When a catalog asset contains more items than this limit, the creative agent selects the top items based on relevance or catalog ordering. When item_limit exceeds the format's max_items, the creative agent SHOULD use the lesser of the two. Ignored when the manifest contains no catalog assets. Distinct from max_creatives, which fans OUT across catalog items to produce one distinct creative per item.
Optionalinclude_preview?: booleanWhen true, requests the creative agent to include preview renders in the response alongside the manifest. Agents that support this return a 'preview' object in the response using the same structure as preview_creative. Agents that do not support inline preview simply omit the field. This avoids a separate preview_creative round trip for platforms that generate previews as a byproduct of building.
Optionalpreview_inputs?: {Input sets for preview generation when include_preview is true. Each input set defines macros and context values for one preview variant. If include_preview is true but this is omitted, the agent generates a single default preview. Only supported with target_format_id (single-format requests). Ignored when using target_format_ids — multi-format requests generate one default preview per format. Ignored when include_preview is false or omitted.
Optionalpreview_quality?: CreativeQualityOptionalpreview_output_format?: PreviewOutputFormatOptionalmacro_values?: { [k: string]: string | undefined }Macro values to pre-substitute into the output manifest's assets. Keys are universal macro names (e.g., CLICK_URL, CACHEBUSTER); values are the substitution strings. The creative agent translates universal macros to its platform's native syntax. Substitution is literal — all occurrences of each macro in output assets are replaced with the provided value. The caller is responsible for URL-encoding values if the output context requires it. Macros not provided here remain as {MACRO} placeholders for the sales agent to resolve at serve time. Creative agents MUST ignore keys they do not recognize — unknown macro names are not an error.
Client-generated unique key for this request. Prevents duplicate creative generation on retries. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.
Optionalpush_notification_config?: PushNotificationConfigOptionalcontext?: ContextObjectOptionalext?: ExtensionObject
Request to transform, generate, refine, or retrieve a creative manifest. Supports four modes: (1) generation from a brief or seed assets, (2) transformation of an existing manifest, (3) refinement of a prior produced variant via refine_from_build_variant_id (re-build with a natural-language message + config delta), (4) retrieval from a creative library by creative_id. Produces target manifest(s) in the specified format(s). Provide either target_format_id for a single format or target_format_ids for multiple formats.