@adcp/client API Reference - v3.3.3
    Preparing search index...

    Interface CreativeFormat

    Creative format definition (per AdCP v2.0.0 spec)

    Extends the official Format type from the schema with an additional agent_url field for convenience when working with creative agents.

    interface CreativeFormat {
        agent_url: string;
        format_id: FormatID;
        name: string;
        description?: string;
        preview_image?: string;
        example_url?: string;
        type: FormatCategory;
        accepts_parameters?: FormatIDParameter[];
        renders?: [
            { [k: string]: unknown }
            | { parameters_from_format_id: true },
            ...({ [k: string]: unknown } | { parameters_from_format_id: true })[],
        ];
        assets_required?: (
            | {
                item_type: "individual";
                asset_id: string;
                asset_type: AssetContentType;
                asset_role?: string;
                required?: boolean;
                requirements?: { [k: string]: unknown };
            }
            | {
                item_type: "repeatable_group";
                asset_group_id: string;
                min_count: number;
                max_count: number;
                assets: {
                    asset_id: string;
                    asset_type: AssetContentType1;
                    asset_role?: string;
                    required?: boolean;
                    requirements?: { [k: string]: unknown };
                }[];
            }
        )[];
        delivery?: { [k: string]: unknown };
        supported_macros?: string[];
        output_format_ids?: FormatID1[];
        format_card?: { format_id: FormatID2; manifest: { [k: string]: unknown } };
        format_card_detailed?: {
            format_id: FormatID3;
            manifest: { [k: string]: unknown };
        };
    }

    Hierarchy (View Summary)

    Index

    Properties

    agent_url format_id name description? preview_image? example_url? type accepts_parameters? renders? assets_required? delivery? supported_macros? output_format_ids? format_card? format_card_detailed?

    Properties

    agent_url: string

    Base URL of the creative agent that provides this format

    format_id: FormatID
    name: string

    Human-readable format name

    description?: string

    Plain text explanation of what this format does and what assets it requires

    preview_image?: string

    DEPRECATED: Use format_card instead. Optional preview image URL for format browsing/discovery UI. Should be 400x300px (4:3 aspect ratio) PNG or JPG. Used as thumbnail/card image in format browsers. This field is maintained for backward compatibility but format_card provides a more flexible, structured approach.

    example_url?: string

    Optional URL to showcase page with examples and interactive demos of this format

    type: FormatCategory
    accepts_parameters?: FormatIDParameter[]

    List of parameters this format accepts in format_id. Template formats define which parameters (dimensions, duration, etc.) can be specified when instantiating the format. Empty or omitted means this is a concrete format with fixed parameters.

    renders?: [
        { [k: string]: unknown }
        | { parameters_from_format_id: true },
        ...({ [k: string]: unknown } | { parameters_from_format_id: true })[],
    ]

    Specification of rendered pieces for this format. Most formats produce a single render. Companion ad formats (video + banner), adaptive formats, and multi-placement formats produce multiple renders. Each render specifies its role and dimensions.

    1

    assets_required?: (
        | {
            item_type: "individual";
            asset_id: string;
            asset_type: AssetContentType;
            asset_role?: string;
            required?: boolean;
            requirements?: { [k: string]: unknown };
        }
        | {
            item_type: "repeatable_group";
            asset_group_id: string;
            min_count: number;
            max_count: number;
            assets: {
                asset_id: string;
                asset_type: AssetContentType1;
                asset_role?: string;
                required?: boolean;
                requirements?: { [k: string]: unknown };
            }[];
        }
    )[]

    Array of required assets or asset groups for this format. Each asset is identified by its asset_id, which must be used as the key in creative manifests. Can contain individual assets or repeatable asset sequences (e.g., carousel products, slideshow frames).

    Type Declaration

    • {
          item_type: "individual";
          asset_id: string;
          asset_type: AssetContentType;
          asset_role?: string;
          required?: boolean;
          requirements?: { [k: string]: unknown };
      }
      • item_type: "individual"

        Discriminator indicating this is an individual asset requirement

      • asset_id: string

        Unique identifier for this asset. Creative manifests MUST use this exact value as the key in the assets object.

      • asset_type: AssetContentType
      • Optionalasset_role?: string

        Optional descriptive label for this asset's purpose (e.g., 'hero_image', 'logo'). Not used for referencing assets in manifests—use asset_id instead. This field is for human-readable documentation and UI display only.

      • Optionalrequired?: boolean

        Whether this asset is required

      • Optionalrequirements?: { [k: string]: unknown }

        Technical requirements for this asset (dimensions, file size, duration, etc.). For template formats, use parameters_from_format_id: true to indicate asset parameters must match the format_id parameters (width/height/unit and/or duration_ms).

    • {
          item_type: "repeatable_group";
          asset_group_id: string;
          min_count: number;
          max_count: number;
          assets: {
              asset_id: string;
              asset_type: AssetContentType1;
              asset_role?: string;
              required?: boolean;
              requirements?: { [k: string]: unknown };
          }[];
      }
      • item_type: "repeatable_group"

        Discriminator indicating this is a repeatable asset group

      • asset_group_id: string

        Identifier for this asset group (e.g., 'product', 'slide', 'card')

      • min_count: number

        Minimum number of repetitions required

      • max_count: number

        Maximum number of repetitions allowed

      • assets: {
            asset_id: string;
            asset_type: AssetContentType1;
            asset_role?: string;
            required?: boolean;
            requirements?: { [k: string]: unknown };
        }[]

        Assets within each repetition of this group

    delivery?: { [k: string]: unknown }

    Delivery method specifications (e.g., hosted, VAST, third-party tags)

    supported_macros?: string[]

    List of universal macros supported by this format (e.g., MEDIA_BUY_ID, CACHEBUSTER, DEVICE_ID). Used for validation and developer tooling.

    output_format_ids?: FormatID1[]

    For generative formats: array of format IDs that this format can generate. When a format accepts inputs like brand_manifest and message, this specifies what concrete output formats can be produced (e.g., a generative banner format might output standard image banner formats).

    format_card?: { format_id: FormatID2; manifest: { [k: string]: unknown } }

    Optional standard visual card (300x400px) for displaying this format in user interfaces. Can be rendered via preview_creative or pre-generated.

    Type Declaration

    • format_id: FormatID2
    • manifest: { [k: string]: unknown }

      Asset manifest for rendering the card, structure defined by the format

    format_card_detailed?: {
        format_id: FormatID3;
        manifest: { [k: string]: unknown };
    }

    Optional detailed card with carousel and full specifications. Provides rich format documentation similar to ad spec pages.

    Type Declaration

    • format_id: FormatID3
    • manifest: { [k: string]: unknown }

      Asset manifest for rendering the detailed card, structure defined by the format

    Settings

    Member Visibility

    On This Page

    Properties