Image Playground API：SwiftUI Sheet、程式化 Image Creator 及樣式控制

Apple Intelligence 的 Image Playground 為應用程式提供兩條整合路徑。SwiftUI 的 imagePlaygroundSheet() 修飾符會呈現系統面向使用者的圖像生成 UI；開發者交出起始概念（文字或圖像），使用者在 sheet 內進行迭代，結果則回傳給應用程式。ImageCreator API 則以程式化方式執行相同的生成流程：開發者提供一個 ImagePlaygroundConcept 物件陣列加上一種樣式，框架便會回傳生成的圖像，無須顯示任何 UI¹。這兩條路徑針對不同的使用情境。當使用者應該進行迭代時，sheet 整合方式較為合適；當應用程式有特定的生成需求並直接呈現結果時，程式化整合則更為適用。

本文將對照 Apple 的官方文件來說明此 API。核心問題是「哪一條整合路徑符合使用者的心智模型」，因為選錯路徑會產生兩種糟糕的 UX：要麼從使用者手中奪走過多的控制權（使用者想迭代時卻採用程式化方式），要麼控制權太少（使用者期望一次到位的結果時卻採用 sheet）。

重點摘要

• imagePlaygroundSheet(isPresented:concept:sourceImage:onCompletion:onCancellation:) 是用於呈現系統 Image Playground sheet 的 SwiftUI 修飾符。使用者進行迭代；應用程式透過 onCompletion 接收所選圖像的 URL（非選擇性 URL）；取消時則觸發 onCancellation²。
• ImageCreator().images(for: [ImagePlaygroundConcept], style: ImagePlaygroundStyle, limit: Int) 是程式化路徑（iOS 18.4 以上）。此方法會回傳一個 ImageCreator.CreatedImage 結果的 AsyncSequence³。
• ImagePlaygroundConcept 承載模型所使用的輸入：文字描述（.text("a watercolor of a cat")）、來源圖像（.image(...)）、繪圖（.drawing(...)），或從參考內容中萃取的概念（.extracted(from:title:)）。
• ImagePlaygroundStyle 用於選擇視覺美學風格。應用程式透過查詢 ImageCreator().availableStyles 來得知裝置支援哪些選項。
• .imagePlaygroundPersonalizationPolicy(_:) 接受 .automatic、.enabled 或 .disabled。.imagePlaygroundGenerationStyle(_:in:) 則接受偏好樣式以及一份允許樣式清單。在隱私敏感或美學鎖定的情境中可使用這些修飾符。

兩條路徑：Sheet 與程式化

兩條整合路徑之間的抉擇，關鍵在於誰來掌控迭代過程。

Sheet 整合將系統完整的圖像生成 UI 交給使用者。使用者輸入提示詞、挑選變體並選擇最終圖像。應用程式的工作是以起始概念啟動 sheet，並接收所選結果。在以下情境採用此路徑：

• 使用者懷有應用程式無法完全預測的創作意圖。
• 互動屬於創作工作流程的一部分（訊息應用程式、筆記應用程式、個人檔案自訂流程）。
• 使用者期望在確認之前先進行迭代。

程式化整合則直接讓應用程式取用模型。應用程式提供概念並取回圖像，不顯示任何系統 UI。在以下情境採用此路徑：

• 生成作業屬於非互動式流程（系統生成的頭像、食譜卡片的固定素材、一次性插圖）。
• 應用程式有特定的美學需求（永遠採用插畫風格、永遠只生成一張圖像）。
• 使用者不應看見迭代過程；他們在意的只是結果本身。

兩條路徑共用底層模型，並遵循相同的使用者層級 Apple Intelligence 設定。選擇純粹取決於 UX。

SwiftUI Sheet

imagePlaygroundSheet 在 View 上提供多種多載變體。標準的 5 參數版本接受起始概念、選擇性的來源圖像參考，以及完成與取消的處理閉包²：

import ImagePlayground
import SwiftUI

struct ProfileEditor: View {
    @State private var showPlayground = false
    @State private var avatarURL: URL?

    var body: some View {
        VStack {
            if let avatarURL {
                AsyncImage(url: avatarURL) { image in
                    image.resizable().scaledToFit()
                } placeholder: {
                    ProgressView()
                }
            }

            Button("Generate Avatar") {
                showPlayground = true
            }
        }
        .imagePlaygroundSheet(
            isPresented: $showPlayground,
            concept: "a friendly cartoon avatar",
            sourceImage: nil,
            onCompletion: { url in
                avatarURL = url
            },
            onCancellation: {
                // user dismissed without choosing
            }
        )
    }
}

此 sheet 的 UX 由系統掌控。使用者看到的是 Apple 標準的 Image Playground 介面（提示詞、樣式選擇器、變體網格、「完成」按鈕）。應用程式的角色僅是提供起始提示詞並接收結果。取消時觸發專用的 onCancellation 閉包，而非在完成處理中傳入 nil URL；傳給 onCompletion 的 URL 為非選擇性型別。

對於希望提供比單一字串更豐富起始概念的應用程式，相關多載直接接受 [ImagePlaygroundConcept]。多個概念可以組合：模型會將每個概念視為約束或訊號。順序很重要：文字概念建立提示詞；圖像概念建立視覺參考；繪圖概念建立輪廓。

ImagePlaygroundConcept 變體

Apple 提供多種 ImagePlaygroundConcept 建構子⁴：

.text(_:)。 簡短的文字描述。最常見的起始概念。

.image(_:)。 來源圖像（通常是 URL 或 UIImage/NSImage）。模型會將其作為樣式或構圖的視覺參考。

.drawing(_:)。 繪圖內容，通常來自 PencilKit 或自訂繪圖介面。模型會將筆觸解讀為結構提示。

.extracted(from:title:)。 從分析過的圖像中萃取的概念。雙參數形式接受來源 URL（或圖像型別）以及描述萃取內容的 title。框架會運用裝置端分析從參考內容衍生出適合生成用途的概念。

概念可以組合：將 [text, image, extracted] 傳給 sheet 或 ImageCreator，可讓模型同時滿足多項約束。正確的模式是「具體到能產生有用輸出，但又寬鬆到讓模型有發揮空間」：一兩個明確的概念，加上選擇性的參考影像。

ImageCreator：程式化路徑

ImageCreator 是供應用程式在無需 UI 情況下進行生成的程式化 API³：

import ImagePlayground

do {
    let creator = try ImageCreator()

    // Discover the styles the device supports
    guard let style = creator.availableStyles.first else {
        // Apple Intelligence unavailable on this device
        return
    }

    let stream = creator.images(
        for: [.text("a friendly cartoon avatar")],
        style: style,
        limit: 1
    )

    for try await result in stream {
        // result is an ImageCreator.CreatedImage
        await self.save(result)
    }
} catch {
    // ImageCreator() initializer can throw on unsupported devices
    print("Generation failed: \(error)")
}

images(for:style:limit:) 方法會回傳一個 ImageCreator.CreatedImage 結果的 AsyncSequence。非同步串流模型讓應用程式得以呈現部分結果（模型的漸進式精煉），或等待最終圖像。limit: 參數會限制請求的圖像數量；Apple 可能會根據策略或裝置狀態回傳較少的結果。

程式化路徑要求 iOS 18.4 以上，並需要支援 Apple Intelligence 且已啟用該功能的裝置。可用性檢查的模式為：在 try 中建構 ImageCreator，再讀取 availableStyles。空的 availableStyles 集合（或建構子拋出例外）代表目前裝置無法進行生成；應用程式應退回到非生成式的路徑（素材庫、使用者上傳的圖像等）。

ImagePlaygroundStyle 變體

樣式參數會約束視覺美學風格⁵：

• .animation。 Apple 的動畫角色風格（圓潤造型、粗體外框、簡化的特徵）。適合用於頭像、吉祥物、風格友善的 UI 插畫。
• .illustration。 帶有向量風格美學的扁平插畫風格。適合用於資訊圖表、食譜卡片、概念性影像。
• .sketch。 鉛筆素描風格（在較新版本中加入）。適合用於筆記應用程式、日誌寫作、手繪美學。

希望生成圖像具有一致美學風格的應用程式（每個頭像都採用 .animation、每張食譜卡片都採用 .illustration）會在生成呼叫中鎖定樣式；想要將選擇權交給使用者的應用程式，則會提供樣式選擇器，對應到可用的選項。

個人化與策略修飾符

兩個 SwiftUI 修飾符讓應用程式能在自身情境中約束 Image Playground 的行為⁶：

.imagePlaygroundPersonalizationPolicy(_:)。 接受 ImagePlaygroundPersonalizationPolicy 值：.automatic（系統預設）、.enabled（明確允許），或 .disabled（禁止系統參考個人內容如聯絡人/照片）。在隱私敏感的情境中（醫療、金融、匿名通訊）請使用 .disabled。

.imagePlaygroundGenerationStyle(_:in:)。 接受偏好樣式以及一份允許樣式陣列。使用者的樣式選擇器（若顯示）會被限縮到允許清單，而偏好樣式則作為預設值。當應用程式的美學需要約束或鎖定可用樣式時，請採用此修飾符。

兩個修飾符都將系統層級的 Apple Intelligence 設定視為下限。應用程式無法覆寫系統已停用的功能；只能進一步收緊限制。

常見錯誤

從 Image Playground 整合紀錄中歸納出三種模式：

呼叫 ImageCreator() 卻未捕捉建構子錯誤。 在不支援 Apple Intelligence 的裝置上，建構子會在初始化時拋出例外。沒有使用 try 並捕捉例外的應用程式，會向使用者呈現令人困惑的錯誤。修正方式：將 ImageCreator() 包裹在 try 中，檢查 availableStyles，並在失敗時提供退路（顯示佔位內容、提示使用者於「設定」中啟用 Apple Intelligence，或完全隱藏該功能）。

整合路徑與使用情境不匹配。 使用 ImageCreator 的個人檔案頭像生成器產出使用者無法調整的一次性頭像；使用 sheet 的一次性頭像生成器則會增加摩擦。請讓路徑配合使用者的期待：想要迭代就用 sheet；想要結果就用程式化方式。

忽視系統的策略下限。 試圖繞過系統 Apple Intelligence 設定的應用程式（例如在使用者已全域停用的情境中生成圖像），會遇到策略錯誤。修正方式：尊重系統設定；當 Apple Intelligence 被停用時，呈現有意義的錯誤訊息，而非靜默失敗。

此模式對 Apple Intelligence 應用程式的意義

三點重要結論。

1. 依使用者的心智模型挑選整合路徑。 創作迭代用 sheet；非互動流程的一次性生成用程式化。挑錯的代價是真實的 UX 摩擦。

2. 刻意約束樣式與個人化。 想要一致頭像風格的訊息應用程式會將單一允許樣式傳給 .imagePlaygroundGenerationStyle(_:in:)。注重隱私的日誌應用程式會設定 .imagePlaygroundPersonalizationPolicy(.disabled)。預設值較為寬鬆（.automatic）；刻意的約束能讓功能顯得有意圖。

3. 務必檢查 ImageCreator() 的 availableStyles（或捕捉建構子錯誤）並準備退路。 Apple Intelligence 需要特定硬體（iPhone 15 Pro 以後機型、M 系列 Mac）外加使用者主動啟用。倚賴 Image Playground 卻不做可用性檢查的應用程式，在較舊裝置以及停用 Apple Intelligence 的裝置上會莫名失敗。

完整的 Apple 生態系列：型別化的 App Intents；MCP 伺服器；路由問題；Foundation Models；執行階段與工具LLM的區別；三個介面；單一真實來源模式；兩部 MCP 伺服器；Apple 開發的 hooks；Live Activities；watchOS 執行階段；SwiftUI 內部結構；RealityKit 的空間心智模型；SwiftData schema 紀律；Liquid Glass 模式；多平台出貨；平台矩陣；Vision 框架；Symbol Effects；Core ML 推論；Writing Tools API；Swift Testing；Privacy Manifest；將無障礙視為平台；SF Pro 字體系統；visionOS 空間模式；Speech 框架；SwiftData 遷移；tvOS 焦點引擎；@Observable 內部結構；SwiftUI Layout 協定；自訂 SF Symbols；AVFoundation HDR；watchOS 訓練生命週期；iOS 26 中的 App Intents 2.0；我拒絕撰寫的主題。彙整中心位於 Apple 生態系列。如需 iOS 與 AI 代理的更廣泛背景，請參閱 iOS 代理開發指南。

FAQ

我需要處理 Apple Intelligence 不可用的情況嗎？

需要。Image Playground 需要支援 Apple Intelligence 的裝置（iPhone 15 Pro 以後機型、M 系列 Mac）並啟用該功能。在不支援的裝置上，sheet 不會呈現，而 ImageCreator() 會在初始化時拋出例外。檢查模式為：將 ImageCreator() 包在 try 中並檢查 availableStyles；空的集合或拋出的建構子代表生成功能不可用。請為不支援的使用者提供非生成式的退路。

我可以自訂 sheet 的 UI 嗎？

不行。Sheet 由系統掌控。應用程式提供起始概念並接收結果；中間的所有過程都是 Apple 的 UI。若需要自訂 UI，請改用 ImageCreator 程式化 API，並在其周圍打造自己的迭代介面。

當使用者關閉 sheet 時，生成的圖像會發生什麼事？

5 參數版本的 imagePlaygroundSheet 多載提供獨立的 onCompletion 與 onCancellation 閉包。當使用者選擇圖像時，onCompletion 會以非選擇性 URL 觸發；當使用者未選擇便關閉時，則觸發 onCancellation。暫時的圖像資料會由系統清理；想保留圖像的應用程式必須在完成處理閉包中將其儲存至自家儲存空間。

Image Playground 與相片權限如何互動？

Sheet 本身不需要存取相片圖庫。若使用者在 sheet 內部參考自己的相片圖庫（瀏覽要作為概念使用的圖像），sheet 會在內部處理權限提示。應用程式不需要為了 Image Playground 整合而事先請求相片權限。

我可以在背景中生成圖像嗎？

ImageCreator 在前景執行；框架會管理生成所需的系統資源。希望在背景進行圖像生成的應用程式必須讓自身保持在前景（或在允許持續執行的工作階段類型中，如 watchOS 訓練生命週期中介紹的訓練工作階段）。

這與 Foundation Models LLM 有何關係？

Image Playground 的模型與 Foundation Models 裝置端 LLM（於 Foundation Models 裝置端 LLM 中介紹）是分開的。兩者共用 Apple Intelligence 框架基礎建設，但使用不同的專用模型。同時結合兩者的應用程式（由 LLM 生成提示詞再餵給圖像生成）會將兩個 API 串接組合使用。

參考資料