TheBuilder.AIImageDisclosure.OpenAI 0.2.0

<p align="center"> <img src="https://raw.githubusercontent.com/thebuilder/umbraco-ai-image-disclosure/refs/heads/main/apps/docs/public/logo-mark.svg" width="112" height="112" alt="AI Image Disclosure logo" /> </p>

<h1 align="center">AI Image Disclosure for Umbraco</h1>

<p align="center"> Check Umbraco images for signed C2PA evidence of AI use.<br /> Editors review the result, and your website decides how to label it. </p>

AI Image Disclosure reads C2PA Content Credentials when you upload or replace a file on Umbraco's default Image media type. It checks the signed claims for evidence of AI generation or editing. Editors can review or override the result. Existing media is not scanned automatically.

You can add an optional OpenAI watermark check for images without C2PA metadata. It requires a separate package and starts disabled.

Neither check guarantees that every AI-generated image will be identified. Missing credentials or a negative watermark result leave the image's origin unknown. The package does not guess from how an image looks.

What it adds

The package adds five properties to the default Image media type:

• aiDisclosure: empty when unknown, generated, or modified.
• aiGenerator: read-only software agent evidence from the AI-relevant C2PA action, when provided by the credential.
• aiDisclosureSource: C2PA, Manual, or empty, plus a backoffice action to resume automatic detection.
• aiDisclosureReason: read-only human-readable reason for the latest automatic result; empty after positive AI detection.
• aiWatermark: read-only OpenAI watermark evidence when the optional fallback is enabled.

Editors can review the classification, generator evidence, and detection source on the media item. The EU AI icons mark classified items in the Media tree and on Media Grid thumbnails. Public sites decide where and how to render their own label.

Detection applies only to Umbraco's default Image media type and only when umbracoFile is uploaded or replaced. The package does not change Umbraco's table view, media pickers, or public pages.

C2PA and EU disclosure

C2PA Content Credentials provide cryptographically verifiable provenance about an image's origin, edits, tools, and use of AI. AI Image Disclosure validates that evidence before mapping it to a simple editorial value.

The European Commission provides optional icons for fully AI-generated and partially AI-modified content as part of its guidance for EU AI Act Article 50 disclosure workflows. View the official EU icons and placement guidance. Using an icon does not establish legal compliance by itself.

Install

AI Image Disclosure supports Umbraco CMS 17.3 through 18.x on .NET 10.

dotnet add package TheBuilder.AIImageDisclosure

Restart the application after installation. The package creates the AI image disclosure and AI image disclosure source data types and adds five properties to the default Image media type. Uploading or replacing an image runs detection when that media item is saved.

Editors can override the disclosure. This matters because metadata is easy to remove and many AI tools do not emit Content Credentials. Choose Resume automatic detection in aiDisclosureSource to reprocess the current file and leave manual mode.

Backoffice badges are enabled by default. Generated and modified images get an AI generated or AI modified label on their Media Grid thumbnail, and the basic EU AI icon in the Media tree. Watermark-only evidence uses the basic icon in both places. The grid badge extends Umbraco's own media card, so thumbnails, selection and actions stay native. To hide badges while keeping detection and the media properties active, add:

{
  "AIImageDisclosure": {
    "ShowBackofficeBadges": false
  }
}

Optional OpenAI watermark check

The core package works without OpenAI. To add the check, install TheBuilder.AIImageDisclosure.OpenAI. It supports standard .NET configuration without requiring Umbraco.AI:

{
  "AIImageDisclosure": {
    "OpenAI": {
      "Enabled": false,
      "ApiKey": ""
    }
  }
}

Supply the key through .NET user secrets or AIImageDisclosure__OpenAI__ApiKey in your hosting environment. Set Enabled to true to allow image uploads. A key alone does not enable the check. The Settings panel shows configuration status and provides a test using a bundled sample image, without exposing the key.

To reuse an existing Umbraco.AI connection, install the separate TheBuilder.AIImageDisclosure.OpenAI.UmbracoAI adapter and matching Umbraco.AI provider packages. The adapter requires CMS 17.5 or later on 17.x, or CMS 18.x. The direct-key package supports CMS 17.3 through 18.x. Explicit OpenAI configuration settings take precedence over saved connection settings.

Only automatic inspections that find No content credentials can upload an image. Invalid credentials, existing non-AI credentials, and manual overrides do not trigger this fallback. When OpenAI reports a watermark, the package stores OpenAI SynthID detected in aiWatermark and shows an AI detected sign. This does not distinguish generation from editing. A negative result does not prove the image is human-made. See the setup and privacy notes.

Classification policy

Only C2PA manifests whose validation state is Valid or Trusted are considered. The package follows the active manifest and its parent ingredients, then applies these rules:

Composite evidence takes precedence. An image created entirely by AI and then edited without a composite source remains generated; an AI edit signal without that creation evidence is modified. The parser also recognizes the compositedWithTrainedAlgorithmicMedia spelling used in some C2PA guidance.

A missing disclosure never means that an image is human-made.

The detector also reads validated c2pa.metadata declarations using namespaced Iptc4xmpExt:DigitalSourceType, plus the legacy stds.iptc and stds.iptc.photometadata assertion labels. A placed AI component is modified; a removed component does not count, and inputTo ingredients are ignored.

The package leaves images over 64 MiB, manifest JSON over 4 MiB, and stores with more than 1,024 manifests undetermined. Editors can classify these images manually. Detection failures never block a media save.

Core C2PA detection reads embedded Content Credentials locally and never fetches remote manifests. The optional OpenAI fallback sends eligible images to OpenAI only after an administrator enables it.

Administrators can open the AI disclosure scan tab in the Media section to scan existing Image media in batches of up to 50. The dashboard reports scanned, manually preserved, and failed saves, and can stop after the current batch or resume after an error. The scan tracks media IDs up to a limit captured at the start, so deletions do not shift progress and new uploads are left for the next scan. Reloading the page resets the cursor. Installing the optional OpenAI integration reduces requests to one media entity each to bound remote verification time.

Delivery API

When Umbraco's media Delivery API is enabled, request the properties as normal media properties:

GET /umbraco/delivery/api/v2/media/item/{mediaId}?fields=properties[aiDisclosure,aiGenerator,aiDisclosureSource]

Render the public label from aiDisclosure. Treat an empty value as not determined, not as proof that an image is not AI-generated.

Detection boundaries

The package checks signed C2PA claims. A valid signature does not guarantee that every claim is true. Credentials can also be absent or removed.

The optional OpenAI check looks for supported watermarks. It cannot identify AI output from every tool. The package does not use visual AI classifiers, filenames, or unsigned software tags to guess an image's origin.

Platform support

The pinned ContentAuthenticity dependency bundles native C2PA binaries for Windows x64 and Arm64, Linux x64 and Arm64, Linux musl x64 (Alpine), and macOS Arm64. Intel macOS is not included by that dependency release. Restoring the native dependency and publishing the host uses more disk space than a managed-only Umbraco package.

Documentation

Read the complete documentation at ai-image-disclosure.thebuilder.dk.

Development

dotnet test --solution TheBuilder.AIImageDisclosure.slnx
dotnet build samples/TheBuilder.AIImageDisclosure.Example/TheBuilder.AIImageDisclosure.Example.csproj
dotnet pack src/TheBuilder.AIImageDisclosure/TheBuilder.AIImageDisclosure.csproj --configuration Release
pnpm docs:dev

The integration suite contains a generated OpenAI PNG with embedded Content Credentials and a supplied Google manifest chain.

NuGet publishing is documented in docs/releasing.md.

License

MIT. See LICENSE and THIRD-PARTY-NOTICES.md.