Image Playground API：SwiftUI 表單、程式化影像產生器與樣式控制

更新（2026年6月11日）： Apple 即將停用本文介紹的程式化途徑 ImageCreator。它在 iOS 27、iPadOS 27、macOS 27 與 visionOS 27 中將停止運作。本文其餘部分介紹的表單式 API 仍是受支援的途徑。完整時程與遷移方式請參閱完整的棄用文章。

Apple Intelligence 的 Image Playground 為應用程式提供兩條整合途徑。SwiftUI 的 imagePlaygroundSheet() 修飾符會呈現系統面向使用者的影像產生 UI；開發者交付一個起始概念（文字或影像），使用者在表單內反覆調整，結果再回傳給應用程式。ImageCreator API 則以程式化方式執行相同的產生流程：開發者提供一組 ImagePlaygroundConcept 物件再加上一種樣式，框架便會回傳產生的影像，過程中不會顯示任何 UI¹。這兩條途徑針對的是不同的使用情境。當使用者應該反覆調整時，表單整合最為合適；當應用程式有特定的產生需求並直接呈現結果時，程式化整合才是正解。

本文對照 Apple 的文件逐一檢視這套 API。切入角度是「哪一條整合途徑符合使用者的心智模型」，因為選錯途徑會產生兩種糟糕的 UX：要嘛從使用者手中奪走過多控制權（使用者本想反覆調整，卻被塞進程式化途徑），要嘛給得太少（使用者期待一次成形的結果，卻被丟進表單）。

TL;DR

• imagePlaygroundSheet(isPresented:concept:sourceImage:onCompletion:onCancellation:) 是呈現系統 Image Playground 表單的 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:) 則接受一個偏好樣式與一份允許樣式清單。請在涉及隱私敏感或需鎖定美感的情境中使用這些修飾符。

兩條途徑：表單與程式化

在兩條整合途徑之間做抉擇，關鍵在於由誰掌控反覆調整的過程。

表單整合把系統完整的影像產生 UI 交到使用者手中。使用者輸入提示、挑選變化版本，並選定最終影像。應用程式的職責是帶著起始概念啟動表單，並接收所選的結果。下列情況適用：

• 使用者懷有應用程式無法完全預測的創作意圖。
• 互動屬於某個創作流程的一環（訊息應用程式、筆記應用程式、個人檔案自訂流程）。
• 使用者期望在定案前反覆調整。

程式化整合則直接把模型交給應用程式。應用程式提供概念並取回影像，不顯示系統 UI。下列情況適用：

• 影像產生屬於非互動式流程的一環（系統產生的頭像、食譜卡的確定性素材、一次成形的插圖）。
• 應用程式有特定的美感要求（永遠是插圖樣式、永遠只產生一張影像）。
• 使用者不該看到反覆調整的過程；他們在意的只有結果。

這兩條途徑共用底層的同一個模型，並遵循相同的使用者層級 Apple Intelligence 設定。抉擇純粹是 UX 的問題。

SwiftUI 表單

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
            }
        )
    }
}

表單的 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] 傳給表單或 ImageCreator，可讓模型同時滿足多項約束。正確的取捨是「夠具體才能產出有用的輸出，又夠寬鬆才能留給模型發揮的餘地」：一兩個明確的概念，再加上選用的參考影像。

ImageCreator：程式化途徑

[更新：Apple 已於 2026年6月11日停用 ImageCreator；iOS 27 時程與遷移方式請參閱棄用文章。下方章節作為這套 API 的歷史性文件保留。]

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 包裹並捕捉的應用程式，會向使用者呈現一個令人困惑的錯誤。修正方式：以 try 包裹 ImageCreator()、檢視 availableStyles，並在失敗時提供退路（顯示佔位圖、提示使用者在「設定」中啟用 Apple Intelligence，或乾脆隱藏該功能）。

整合途徑與使用情境不相符。 使用 ImageCreator 的個人檔案頭像產生器，會產出使用者無法微調的一次成形頭像；而使用表單的一次成形頭像產生器，則平添了摩擦。請讓途徑符合使用者的期待：他們想反覆調整就用表單；他們想要一個結果就用程式化。

忽略系統的政策下限。 試圖繞過系統 Apple Intelligence 設定的應用程式（例如，在使用者已全域停用的情境中產生影像），會碰上政策錯誤。修正方式：遵循系統設定；當 Apple Intelligence 被停用時，呈現有意義的錯誤，而非默默失敗。

這套模式對 Apple Intelligence 應用程式的意義

三項要點。

1. 依使用者的心智模型挑選整合途徑。 創作式反覆調整用表單；非互動式流程中的一次成形產生用程式化。選錯的代價，是實實在在的 UX 摩擦。

2. 刻意約束樣式與個人化。 希望維持一致頭像樣式的訊息應用程式，會向 .imagePlaygroundGenerationStyle(_:in:) 傳入單一的允許樣式。注重隱私的寫日誌應用程式，則設定 .imagePlaygroundPersonalizationPolicy(.disabled)。預設值是寬鬆的（.automatic）；刻意的約束才能讓這項功能顯得用心。

3. 務必檢查 ImageCreator() 的 availableStyles（或捕捉初始化器錯誤），並備妥退路。 Apple Intelligence 需要特定硬體（iPhone 15 Pro 以後機型、M 系列 Mac）並加上使用者選擇啟用。倚賴 Image Playground 卻不做可用性檢查的應用程式，在較舊的裝置上、以及在 Apple Intelligence 被停用的裝置上，都會令人困惑地失敗。

完整的 Apple Ecosystem 系列：具型別的 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 Ecosystem 系列。若需要更廣泛的「iOS 結合 AI 代理人」脈絡，請參閱 iOS 代理人開發指南。

FAQ

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

需要。Image Playground 要求一台支援 Apple Intelligence 的裝置（iPhone 15 Pro 以後機型、M 系列 Mac）並啟用該功能。在不支援的裝置上，表單不會呈現，而 ImageCreator() 會在初始化時拋出例外。檢查的模式為：以 try 包裹 ImageCreator() 並檢視 availableStyles；集合為空或初始化器拋出例外，即代表無法進行產生。請為不支援的使用者提供非產生式的退路。

我可以自訂表單的 UI 嗎？

不行。表單由系統掌控。應用程式提供起始概念並接收結果；中間的一切都是 Apple 的 UI。如果你需要自訂 UI，請改用 ImageCreator 程式化 API，並圍繞它打造自己的反覆調整介面。

當使用者關閉表單時，已產生的影像會怎麼樣？

5 參數的 imagePlaygroundSheet 多載提供各自獨立的 onCompletion 與 onCancellation 閉包。當使用者選定一張影像時，onCompletion 會帶著一個非可選的 URL 觸發；當使用者未選定就關閉時，onCancellation 會觸發。暫時的影像資料會由系統清理；希望保留影像的應用程式，必須在完成處理常式中將其儲存到自身的儲存空間。

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

表單本身不需要存取相片庫。如果使用者在表單內參考自己的相片庫（瀏覽某張影像以作為概念使用），表單會在內部處理權限提示。應用程式無需為了 Image Playground 整合而預先請求相片權限。

我可以在背景產生影像嗎？

ImageCreator 在前景執行；框架會管理產生所需的系統資源。希望在背景產生影像的應用程式，需要讓自己的應用程式維持在前景（或處於某種允許持續執行的工作階段型別中，例如 watchOS 健身生命週期所介紹的健身工作階段）。

這與 Foundation Models LLM 有什麼關聯？

Image Playground 的模型與 Foundation Models 裝置端 LLM（於 Foundation Models 裝置端 LLM 中介紹）是分開的。兩者共用 Apple Intelligence 框架基礎設施，但使用各自不同的專用模型。將兩者結合的應用程式（由 LLM 產生的提示餵入影像產生），會依序串接這兩套 API。

參考資料