Managed product media

Preview

The route is implemented, but the owner contract is not yet promoted to stable.

Media uses two steps:

1. register a source through POST /api/v1/media-references;
2. attach the returned media_ref_id in a product sync media[] block.

For product cards, include public_product_card in allowed_purposes, set retain_copy: true, and provide retain_until. To-AI copies the image into managed tenant-scoped storage and later serves a controlled public_delivery_url. The original source URL is never returned as the card URL.

The temporary source must be HTTPS and remain valid for at least six hours. content.file_size_bytes is required; the current maximum is 25 MiB. Supported formats are JPEG, PNG, and WebP. When supplied, checksum_sha256 is exactly 64 hexadecimal characters. The current retention maximum is 90 days, and training_use_allowed must be false.

Product sync accepts only media_ref_id, optional role, and optional non-negative position in each media[] entry. Card alt text is derived from governed product facts; do not send an alt_text media field.

Poll the media reference until asset_status is ready before launch. Revocation removes future public delivery; clients must tolerate 410 and a missing image.

Do not send base64 image bodies in product sync. Do not store a temporary source URL as a permanent storefront asset.