One entry per produced creative group. With catalog fan-out, one entry per catalog item (bounded/sampled by max_creatives). This array is the produced group set; use variants[] inside each group for choose-among alternatives.
Optionalbuild_creative_id?: stringBuild-time handle for this produced creative within this response. Distinct from a library creative_id — a build_creative_id is not yet persisted/servable; it acquires a creative_id when a chosen variant is trafficked or added to the library (lazy promotion).
Optionalcatalog_item_ref?: { catalog_type?: string; item_id: string }When this creative was produced by fanning out over a catalog, identifies the source item.
Optionalcatalog_type?: stringThe catalog type the item came from.
Identifier of the catalog item this creative was built for.
Optionalsignal_condition?: {}Optionalvariants?: {Choose-among alternatives produced for this creative group (voices, themes, best-of-N, etc.). At least one. Each is an independently-tagged, independently-billed build.
Optionalerrors?: Error[]Per-creative errors when this catalog item failed to build. Present only on failed items; does not fail the batch (per-item non-atomic). A failed entry carries errors[] and no variants[]; a successful entry carries variants[] and SHOULD NOT carry errors.
Optionalitems_Total catalog items eligible for the build (before max_creatives sampling). Lets the buyer see that creatives[] is a sample of a larger set.
Optionalitems_Number of creatives returned in creatives[] (after max_creatives sampling).
Optionalleaves_Total leaves the request would have produced (≈ items_to_produce × variants_per_item, × conditions_total when signal_conditions was sent). Present when a max_spend cap may have stopped production short. Counts LEAVES, not catalog items — so it expresses a shortfall even for a variant-only fan-out with no catalog.
Optionalleaves_Number of leaves actually produced and billed across creatives[].variants[]. When budget_status is 'capped', leaves_returned < leaves_total is the leaf-granular shortfall signal (items_returned/items_total are catalog-item counts and do not capture a mid-item or variant-only cap).
Optionalvendor_Aggregate cost across all variant leaves, denominated in currency. MUST equal the sum of the per-leaf vendor_cost values (leaves are the source of truth). When present, every produced leaf MUST carry its own vendor_cost + currency (enforced) so the sum invariant is checkable; omit this aggregate only for a genuinely free build.
OptionalcurrencyISO 4217 currency code for the aggregate vendor_cost.
Optionalkeep_Echoes the keep_mode the agent applied (mirrors the request hint). Present when the request set keep_mode. keep_mode is advisory — it does not change what is produced or billed (you pay for every leaf in variants[]) — so this echo is the buyer's confirmation that the hint was received, the audit paper trail for a 'I asked for keep_one but was billed for N' dispute. Whether the agent acted on it shows in the recommended/rank it set on the leaves.
Optionalselection_Optionalbudget_complete (default; absent == complete for back-compat) means the agent produced everything requested. capped means a max_spend ceiling stopped production early: every returned leaf is real/billed, and an advisory BUDGET_CAP_REACHED entry in errors[] is the authoritative cap signal. The leaf-granular shortfall is leaves_returned < leaves_total (do NOT rely on items_returned < items_total — that is also the normal max_creatives-sampling signal and does not capture a mid-item or variant-only cap). This is a successful partial build, not a failure.
OptionalerrorsAdvisory (non-terminal) entries on an otherwise-successful build — e.g. a BUDGET_CAP_REACHED notice when budget_status is capped. Terminal failures use the BuildCreativeError shape, not this field.
OptionalsandboxWhen true, this response contains simulated data from sandbox mode.
Optionalexpires_ISO 8601 timestamp when the earliest generated asset URL expires across all variants. Re-build after this time to get fresh URLs.
OptionalcontextOptionalext
Multiplicity success response. Returned WHENEVER the request used max_creatives, max_variants > 1, variant_axis, or refine_from_build_variant_id — with or without a transformer_id. There is no fallback to the single/multi-format shapes: a client that sends any of those inputs MUST handle this
creatives[]shape; it will not receivecreative_manifest/creative_manifests. Carries creatives[] — one entry per produced creative group (per catalog item when fanning out) — each holding variants[] alternatives. The envelope semantics are fixed: creatives[] is the set of creative groups the call produced; variants[] is the choose-among set within each group. Every produced variant is a real, independently-billed build (you pay for all produced); the buyer keeps one or many by trafficking the chosen build_variant_id(s). Mutually exclusive with the other success/error/submitted shapes. Per-FORMAT remains atomic within a (creative) group; per-ITEM (catalog fan-out) is non-atomic — a failed item is reported via that creative's errors[] and does not fail the batch.