Module adcp.types.domains.formats.canonical.image

Classes

class AssetSource (*args, **kwds)

Expand source code

class AssetSource(StrEnum):
    buyer_uploaded = 'buyer_uploaded'
    publisher_host_recorded = 'publisher_host_recorded'
    seller_pre_rendered_from_brief = 'seller_pre_rendered_from_brief'
    seller_human_designed = 'seller_human_designed'
    agent_synthesized = 'agent_synthesized'
    publisher_owned_reference = 'publisher_owned_reference'

Enum where members are also (and must be) strings

Ancestors

• enum.StrEnum
• builtins.str
• enum.ReprEnum
• enum.Enum

Class variables

var agent_synthesized

var buyer_uploaded

var publisher_host_recorded

var publisher_owned_reference

var seller_human_designed

var seller_pre_rendered_from_brief

class BuyerAssetAcceptance (*args, **kwds)

Expand source code

class BuyerAssetAcceptance(StrEnum):
    accepted = 'accepted'
    rejected = 'rejected'

Enum where members are also (and must be) strings

Ancestors

• enum.StrEnum
• builtins.str
• enum.ReprEnum
• enum.Enum

Class variables

var accepted

var rejected

class CanonicalFormatImage (**data: Any)

Expand source code

class CanonicalFormatImage(CanonicalFormatBase):
    model_config = ConfigDict(
        extra='allow',
    )
    motion_level: MotionLevel | None = None
    slots: Annotated[
        Any | None,
        Field(
            description="Default slots for image canonical. Buyer ships an image asset (file or hosted URL) plus optional headline, body text, primary text (long-form caption), CTA (typically constrained to an enum via `cta_values`), and clickthrough URL. Products MAY override the default — make `headline` required, narrow `cta` to a value enum, or remove slots the surface doesn't consume."
        ),
    ] = [
        {'asset_group_id': 'image_main', 'asset_type': 'image', 'required': True},
        {'asset_group_id': 'headline', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'body_text', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'primary_text', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'cta', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'landing_page_url', 'asset_type': 'url', 'required': False},
    ]
    width: Annotated[
        SchemaInt | None,
        Field(
            description="Logical render width in pixels — use for fixed-size slots (e.g., a 300×250 IAB MREC). When `pixel_ratios` is absent, the required image asset width is the same value (1x). When `pixel_ratios` is present, an accepted asset's intrinsic width is `width × pixel_ratio`. For multi-size flexible slots, use `sizes[]`; for responsive slots, use the min/max fields. The three size modes are mutually exclusive.",
            ge=1,
        ),
    ] = None
    height: Annotated[
        SchemaInt | None,
        Field(
            description='Logical render height in pixels. Intrinsic asset height is `height × pixel_ratio`, where the ratio defaults to 1 when `pixel_ratios` is absent. See `width` for size-mode mutual exclusion.',
            ge=1,
        ),
    ] = None
    sizes: Annotated[
        list[Size] | None,
        Field(
            description='List of accepted logical (width, height) render pairs for a multi-size flexible slot. The buyer ships an asset matching one logical size multiplied by one accepted `pixel_ratios` entry (or by 1 when `pixel_ratios` is absent). SDKs MUST treat size and density as separate axes: a 600×500 intrinsic asset at 2x satisfies a logical 300×250 size; it does not create a logical 600×500 placement. Mirrors OpenRTB `banner.format[]` semantics. Mutually exclusive with `(width, height)` and with responsive ranges.',
            min_length=1,
        ),
    ] = None
    pixel_ratios: Annotated[
        list[PixelRatio] | None,
        Field(
            description='Accepted intrinsic-pixel densities for image assets, expressed as intrinsic pixels per logical render pixel (for example `[1, 2]` accepts both standard and Retina renditions). Absence means `[1]` for backward compatibility. This is an acceptance set, not a requirement to submit every rendition: one `image_main` asset satisfying any listed ratio is sufficient unless the effective `image_main` slot declares `required_pixel_ratios`. SDKs determine the effective ratio from `asset.pixel_ratio` when supplied, otherwise infer it from intrinsic asset dimensions divided by the matched logical size. Width and height ratios MUST agree.',
            min_length=1,
        ),
    ] = None
    min_width: Annotated[
        SchemaInt | None,
        Field(
            description="Minimum accepted width in pixels for responsive slots that adapt within a range (e.g., 'any width from 300 to 970'). Use with `max_width` (and optionally `min_height`/`max_height`). Mutually exclusive with `(width, height)` and `sizes[]`.",
            ge=1,
        ),
    ] = None
    max_width: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum accepted width in pixels for responsive slots. Pair with `min_width`. See `min_width` for size-mode mutual exclusion.',
            ge=1,
        ),
    ] = None
    min_height: Annotated[
        SchemaInt | None,
        Field(
            description='Minimum accepted height in pixels for responsive slots. Pair with `max_height`.',
            ge=1,
        ),
    ] = None
    max_height: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum accepted height in pixels for responsive slots. Pair with `min_height`.',
            ge=1,
        ),
    ] = None
    aspect_ratio: Annotated[
        str | None,
        Field(
            description="Optional aspect ratio constraint (e.g., '1.91:1', '1:1'). When provided alongside `width`/`height`, must agree. When used with `sizes[]` or responsive ranges, narrows accepted entries to those matching the aspect ratio.",
            pattern='^[0-9]+(\\.[0-9]+)?:[0-9]+(\\.[0-9]+)?$',
        ),
    ] = None
    max_file_size_kb: Annotated[
        SchemaInt | None, Field(description='Maximum file size in kilobytes.', ge=1)
    ] = None
    image_formats: Annotated[
        list[ImageFormat] | None, Field(description='Permitted image file formats.')
    ] = None
    ssl_required: Annotated[
        StrictBool | None,
        Field(description='Whether the image and its trackers must be served over HTTPS.'),
    ] = None
    headline_max_chars: Annotated[SchemaInt | None, Field(ge=1)] = None
    body_text_max_chars: Annotated[SchemaInt | None, Field(ge=1)] = None
    cta_values: Annotated[
        list[str] | None,
        Field(
            description="Permitted CTA values for this product (e.g., ['LEARN_MORE', 'SHOP_NOW'])."
        ),
    ] = None
    asset_source: Annotated[
        AssetSource | None,
        Field(
            description="Where the rendered asset bytes come from. Single shared enum across all canonicals (`image`, `video_hosted`, `audio_hosted` — replaces the earlier per-canonical `image_source` / `video_source` / `audio_source` fields). `buyer_uploaded` (default): buyer ships a pre-rendered asset. `publisher_host_recorded`: publisher's host records the asset (audio-specific; podcast host-read pattern). `seller_pre_rendered_from_brief`: buyer ships a brief plus structured copy; seller renders ONE asset at sync_creatives or build_creative time (generative-DSP pattern). `seller_human_designed`: seller's design team renders manually from a brief. `agent_synthesized`: AI synthesis pipeline; pair with `synthesis_nondeterministic: true` when the platform cannot guarantee in-spec output (Veo/Sora/Imagen-class). `publisher_owned_reference`: buyer references an existing post or publisher-owned object via a `published_post` slot; the seller resolves and serves the referenced content after authorization/review rather than receiving uploaded bytes.\n\nNot every value is meaningful on every canonical — `publisher_host_recorded` is audio-specific; on `image` or `video_hosted` it has no defined behavior. `publisher_owned_reference` is meaningful only when the product's `slots` declaration accepts a reference asset such as `published_post`. Adopters MUST select a value appropriate to the canonical's asset type. The `slots` declaration is the binding contract for what the buyer ships; `asset_source` is informational and lets buyers understand the production model when picking products."
        ),
    ] = AssetSource.buyer_uploaded
    buyer_asset_acceptance: Annotated[
        BuyerAssetAcceptance | None,
        Field(
            description="Whether the product accepts buyer-uploaded assets. When `rejected`, the buyer cannot ship pre-rendered bytes directly — they must use build_creative (or sync_creatives with brief inputs or reference assets) so the seller produces or resolves the asset. Combined with `asset_source`, lets a product declare 'I produce assets from briefs and refuse buyer uploads' (asset_source=`seller_pre_rendered_from_brief`, buyer_asset_acceptance=`rejected`) or 'I accept existing post references, not uploaded bytes' (asset_source=`publisher_owned_reference`, buyer_asset_acceptance=`rejected`)."
        ),
    ] = BuyerAssetAcceptance.accepted
    ctv_ad_experience: Annotated[
        ctv_ad_experience_1.CtvAdExperience | None,
        Field(
            description='CTV experience this option serves. On `image` only `pause` and `screensaver` are valid — the image-plus-copy contract the major pause-ad sellers ingest (seller composites the frame; typical canvas 1920×1080 or a transparent-region overlay). Other experiences route per the matrix in docs/creative/ctv-experiences.mdx.'
        ),
    ] = None
    activation_methods: Annotated[
        list[activation_method.CreativeActivationMethod] | None,
        Field(
            description='Viewer activation mechanisms this option offers (e.g. `qr_code` on a pause frame). Activations are engagement events, not impressions.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• adcp.types.domains.formats.canonical._base.CanonicalFormatBase
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var activation_methods : list[CreativeActivationMethod] | None

var aspect_ratio : str | None

var asset_source : AssetSource | None

var body_text_max_chars : int | None

var buyer_asset_acceptance : BuyerAssetAcceptance | None

var cta_values : list[str] | None

var ctv_ad_experience : CtvAdExperience | None

var headline_max_chars : int | None

var height : int | None

var image_formats : list[ImageFormat] | None

var max_file_size_kb : int | None

var max_height : int | None

var max_width : int | None

var min_height : int | None

var min_width : int | None

var model_config

var motion_level : MotionLevel | None

var pixel_ratios : list[PixelRatio] | None

var sizes : list[Size] | None

var slots : typing.Any | None

var ssl_required : bool | None

var width : int | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ImageFormat (*args, **kwds)

Expand source code

class ImageFormat(StrEnum):
    jpg = 'jpg'
    jpeg = 'jpeg'
    png = 'png'
    gif = 'gif'
    webp = 'webp'
    svg = 'svg'

Enum where members are also (and must be) strings

Ancestors

• enum.StrEnum
• builtins.str
• enum.ReprEnum
• enum.Enum

Class variables

var gif

var jpeg

var jpg

var png

var svg

var webp

class MotionLevel (*args, **kwds)

Expand source code

class MotionLevel(StrEnum):
    static = 'static'
    limited_motion = 'limited_motion'

Enum where members are also (and must be) strings

Ancestors

• enum.StrEnum
• builtins.str
• enum.ReprEnum
• enum.Enum

Class variables

var limited_motion

var static

class PixelRatio (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class PixelRatio(ScalarFloat):
    __slots__ = ()
    _constraints = {'gt': 0.0}

A float generated from a JSON Schema number root.

Strict, like the StrictFloat the generator emits for a type: number field: an int or float is accepted, a bool or numeric string is refused, matching the bundled JSON Schema validator.

Ancestors

• adcp.types._scalar.ScalarFloat
• adcp.types._scalar._ScalarRoot
• builtins.float

class Size (**data: Any)

Expand source code

class Size(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    width: Annotated[SchemaInt, Field(ge=1)]
    height: Annotated[SchemaInt, Field(ge=1)]

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var height : int

var model_config

var width : int

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary