docs(ai): Add Image Generation capability documentation (v17 + v18) by mattbrailsford · Pull Request #8222 · umbraco/UmbracoDocs

mattbrailsford · 2026-07-03T09:29:46Z

📋 Description

Adds documentation for the Image Generation capability in Umbraco.AI, at full parity with the existing capabilities (Chat, Embedding, Speech-to-Text). Image Generation is experimental — gated behind the Umbraco:AI:Experimental:ImageGeneration feature flag and the UMBRACOAI_IMAGEGEN diagnostic — and the docs make that status and enablement prominent throughout.

All content is added identically to both the v17 and v18 doc lines (byte-identical .md files).

New pages (× both 17/ and 18/):

using-the-api/image-generation/ — overview + canonical "Enabling image generation" section, generating-images (text-to-image), editing-images (maskless edit + masked-outpainting escape hatch)
extending/providers/image-generation-capability.md — implementing AIImageGeneratorCapabilityBase<TSettings>
management-api/image-generation/ — section README + generate-image endpoint reference
frontend/image-generation-controller.md — UaiImageGenerationController

Edited pages: capabilities concept, AICapability reference (ImageGeneration = 5), AIOptions config reference (+ Experimental Features section), OpenAI provider page, providers matrix, and SUMMARY.md navigation.

Verified: all SUMMARY.md links resolve, 17↔18 .md parity holds, and cross-page links/anchors are consistent.

📎 Related Issues (if applicable)

N/A

✅ Contributor Checklist

I've followed the Umbraco Documentation Style Guide and can confirm that:

Code blocks are correctly formatted.
Sentences are short and clear (preferably under 25 words).
Passive voice and first-person language (“we”, “I”) are avoided.
Relevant pages are linked.
All links work and point to the correct resources.
Screenshots or diagrams are included if useful.
Any code examples or instructions have been tested.
Typos, broken links, and broken images are fixed.

Product & Version (if relevant)

Umbraco.AI — v17 and v18 (both active support lines). Feature is experimental and not yet released.

Deadline (if relevant)

Aligns with the release of the Image Generation capability (currently experimental / unreleased).

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

… in image generation docs - WithAlias not required for GetSupportedModelsAsync (read-only metadata lookup) - Expand responseFormat descriptions to clarify use cases (URI, base64 data, hosted resource) - Add UMBRACOAI_IMAGEGEN pragma to builder options snippet - Sync edits across v18 and v17 documentation Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-07-03T09:30:14Z

Thanks for opening this PR! 🎉

Quick question: Does this PR include any AI-generated content?

AI tools are absolutely welcome here! We only ask that you follow our AI contribution guidelines to help keep the documentation consistent and trustworthy.

Drop a quick comment to let us know!

github-actions

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

vale

18/ai-in-umbraco/management-api/image-generation/generate-image.md|42 col 58| [UmbracoDocs.Spelling] Check the word 'maskless' for typos.
18/ai-in-umbraco/management-api/image-generation/generate-image.md|42 col 114| [UmbracoDocs.Spelling] Check the word 'outpainting' for typos.
18/ai-in-umbraco/providers/openai.md|8 col 27| [UmbracoDocs.Acronyms] 'GPT' has no definition.
18/ai-in-umbraco/using-the-api/image-generation/generating-images.md|75 col 43| [UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words). For content inside note or warning blocks, add blank lines around the content.
18/ai-in-umbraco/using-the-api/image-generation/generating-images.md|106 col 41| [UmbracoDocs.Spelling] Check the word 'Maskless' for typos.
18/ai-in-umbraco/using-the-api/image-generation/generating-images.md|106 col 66| [UmbracoDocs.Spelling] Check the word 'outpainting' for typos.
18/ai-in-umbraco/using-the-api/image-generation/editing-images.md|3 col 41| [UmbracoDocs.Spelling] Check the word 'maskless' for typos.
18/ai-in-umbraco/using-the-api/image-generation/editing-images.md|3 col 100| [UmbracoDocs.Spelling] Check the word 'outpainting' for typos.
18/ai-in-umbraco/using-the-api/image-generation/editing-images.md|12 col 4| [UmbracoDocs.Spelling] Check the word 'Maskless' for typos.
18/ai-in-umbraco/using-the-api/image-generation/editing-images.md|43 col 11| [UmbracoDocs.Spelling] Check the word 'outpainting' for typos.
18/ai-in-umbraco/using-the-api/image-generation/README.md|18 col 1| [UmbracoDocs.ListStart] List items should start with a capital letter, unless they begin with an inline code or a URL.
18/ai-in-umbraco/using-the-api/image-generation/README.md|19 col 3| [UmbracoDocs.ListStart] List items should start with a capital letter, unless they begin with an inline code or a URL.
18/ai-in-umbraco/using-the-api/image-generation/README.md|20 col 1| [UmbracoDocs.ListStart] List items should start with a capital letter, unless they begin with an inline code or a URL.
18/ai-in-umbraco/using-the-api/image-generation/README.md|59 col 6| [UmbracoDocs.Spelling] Check the word 'Maskless' for typos.
18/ai-in-umbraco/using-the-api/image-generation/README.md|60 col 13| [UmbracoDocs.Spelling] Check the word 'outpainting' for typos.
18/ai-in-umbraco/using-the-api/image-generation/README.md|109 col 83| [UmbracoDocs.Spelling] Check the word 'maskless' for typos.

github-actions · 2026-07-03T09:30:59Z

+The Image Generation capability produces images from text prompts:
+
+- Text-to-image generation
+- Maskless image editing (transform supplied images)


🚫 [vale] _{reported by reviewdog 🐶}
[UmbracoDocs.Spelling] Check the word 'Maskless' for typos.

github-actions · 2026-07-03T09:30:59Z

+
+- Text-to-image generation
+- Maskless image editing (transform supplied images)
+- Provider-native masked outpainting via an escape hatch


🚫 [vale] _{reported by reviewdog 🐶}
[UmbracoDocs.Spelling] Check the word 'outpainting' for typos.

github-actions · 2026-07-03T09:30:59Z

+
+## Exposing a provider-native client (optional)
+
+To let consumers reach your provider's native client for masked outpainting (Tier 3), return an `IImageGenerator` that overrides `GetService` to resolve that client (as the OpenAI provider does with `OpenAIClient`). Wrap the M.E.AI adapter in a `DelegatingImageGenerator` and return your native client for its type in `GetService`.


⚠️ [vale] _{reported by reviewdog 🐶}
[UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words). For content inside note or warning blocks, add blank lines around the content.

github-actions · 2026-07-03T09:30:59Z

+
+## Exposing a provider-native client (optional)
+
+To let consumers reach your provider's native client for masked outpainting (Tier 3), return an `IImageGenerator` that overrides `GetService` to resolve that client (as the OpenAI provider does with `OpenAIClient`). Wrap the M.E.AI adapter in a `DelegatingImageGenerator` and return your native client for its type in `GetService`.


🚫 [vale] _{reported by reviewdog 🐶}
[UmbracoDocs.Spelling] Check the word 'outpainting' for typos.

github-actions · 2026-07-03T09:30:59Z

+
+## Exposing a provider-native client (optional)
+
+To let consumers reach your provider's native client for masked outpainting (Tier 3), return an `IImageGenerator` that overrides `GetService` to resolve that client (as the OpenAI provider does with `OpenAIClient`). Wrap the M.E.AI adapter in a `DelegatingImageGenerator` and return your native client for its type in `GetService`.


🚫 [vale] _{reported by reviewdog 🐶}
[UmbracoDocs.Spacing] '.E' should have one space.

github-actions · 2026-07-03T09:31:00Z

+
+## Exposing a provider-native client (optional)
+
+To let consumers reach your provider's native client for masked outpainting (Tier 3), return an `IImageGenerator` that overrides `GetService` to resolve that client (as the OpenAI provider does with `OpenAIClient`). Wrap the M.E.AI adapter in a `DelegatingImageGenerator` and return your native client for its type in `GetService`.


⚠️ [vale] _{reported by reviewdog 🐶}
[UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words). For content inside note or warning blocks, add blank lines around the content.

github-actions · 2026-07-03T09:31:00Z

+
+## Exposing a provider-native client (optional)
+
+To let consumers reach your provider's native client for masked outpainting (Tier 3), return an `IImageGenerator` that overrides `GetService` to resolve that client (as the OpenAI provider does with `OpenAIClient`). Wrap the M.E.AI adapter in a `DelegatingImageGenerator` and return your native client for its type in `GetService`.


🚫 [vale] _{reported by reviewdog 🐶}
[UmbracoDocs.Spelling] Check the word 'outpainting' for typos.

github-actions · 2026-07-03T09:31:00Z

+
+## Exposing a provider-native client (optional)
+
+To let consumers reach your provider's native client for masked outpainting (Tier 3), return an `IImageGenerator` that overrides `GetService` to resolve that client (as the OpenAI provider does with `OpenAIClient`). Wrap the M.E.AI adapter in a `DelegatingImageGenerator` and return your native client for its type in `GetService`.


🚫 [vale] _{reported by reviewdog 🐶}
[UmbracoDocs.Spacing] '.E' should have one space.

github-actions · 2026-07-03T09:31:00Z

+Image Generation is **experimental**. When the `Umbraco:AI:Experimental:ImageGeneration` feature flag is disabled, these endpoints return **404**. See [Enabling image generation](../../using-the-api/image-generation/README.md#enabling-image-generation).
+{% endhint %}
+
+The Image Generation API generates images from a text prompt, with optional maskless editing of supplied images.


🚫 [vale] _{reported by reviewdog 🐶}
[UmbracoDocs.Spelling] Check the word 'maskless' for typos.

github-actions · 2026-07-03T09:31:00Z

@@ -0,0 +1,92 @@
+---
+description: >-
+    Generate one or more images from a text prompt, with optional maskless edit.


🚫 [vale] _{reported by reviewdog 🐶}
[UmbracoDocs.Spelling] Check the word 'maskless' for typos.

- Add 'maskless' and 'outpainting' to the umbraco dictionary - Add GPT to the Acronyms exceptions list - Wrap Microsoft.Extensions.AI in inline code to satisfy the spacing rule - Capitalize list items and split long sentences Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-07-03T09:39:43Z

The Link Checker found broken links in your PR.
Please review the following list:

Broken links found in: 17/ai-in-umbraco/providers/openai.md

⚠ Unknown error → [403] https://platform.openai.com/ |#124; Rejected status code: 403 Forbidden (configurable with "accept" option)

Broken links found in: 18/ai-in-umbraco/providers/openai.md

⚠ Unknown error → [403] https://platform.openai.com/ |#124; Rejected status code: 403 Forbidden (configurable with "accept" option)

platform.openai.com returns 403 to automated tools (anti-bot). This pre-existing link surfaced when providers/openai.md was edited, since Lychee re-checks all links in changed files. Matches the existing pattern for dotnet.microsoft.com and other 403 hosts. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

mattbrailsford · 2026-07-03T09:55:15Z

Just to note, this is currently draft because the feature isn't released yet and I just wanted to prep the doc PR. Will convert once feature is released.

mattbrailsford and others added 10 commits July 3, 2026 09:29

docs(ai): Add ImageGeneration to AICapability reference

f3c76e0

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(ai): Document Image Generation in the capabilities concept

9e05833

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(ai): Add Image Generation API overview and enablement

29f98d8

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(ai): Add Generating Images guide

0049546

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(ai): Add Editing Images guide

cf27df2

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(ai): Add Image Generation provider capability guide

2de6165

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(ai): Add Image Generation management API reference

9ac0092

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(ai): Add Image Generation frontend controller guide

5630635

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(ai): Note Image Generation support in provider and config docs

1276010

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions Bot reviewed Jul 3, 2026

View reviewed changes

sofietoft added category/umbraco-in-ai ai-generated This PR was written by or with the assistance of AI. labels Aug 10, 2026

mattbrailsford marked this pull request as ready for review September 25, 2026 07:56


		## Exposing a provider-native client (optional)

		To let consumers reach your provider's native client for masked outpainting (Tier 3), return an `IImageGenerator` that overrides `GetService` to resolve that client (as the OpenAI provider does with `OpenAIClient`). Wrap the M.E.AI adapter in a `DelegatingImageGenerator` and return your native client for its type in `GetService`.

Conversation

mattbrailsford commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📋 Description

📎 Related Issues (if applicable)

✅ Contributor Checklist

Product & Version (if relevant)

Deadline (if relevant)

Uh oh!

github-actions Bot commented Jul 3, 2026

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 3, 2026

Uh oh!

mattbrailsford commented Jul 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mattbrailsford commented Jul 3, 2026 •

edited

Loading