Image Playground API：SwiftUI Sheet、プログラム的なImage Creator、そしてスタイル制御

Apple IntelligenceのImage Playgroundは、アプリに2つの統合パスを公開しています。SwiftUIのimagePlaygroundSheet()モディファイアはシステムのユーザー向け画像生成UIを提示するもので、開発者が起点となるコンセプト（テキストまたは画像）を渡し、ユーザーがシート内で反復し、結果がアプリに返されます。ImageCreator API は同じ生成パイプラインをプログラム的に実行します。開発者がImagePlaygroundConceptオブジェクトの配列とスタイルを供給すると、フレームワークはUIを表示することなく生成された画像を返します¹。この2つのパスは異なるユースケースを対象としています。シート統合はユーザーに反復させたいときに適しており、プログラム的な統合はアプリが特定の生成リクエストを持ち、結果を直接表示したいときに適しています。

この記事では、Appleのドキュメントに沿って API を解説していきます。フレームは「どの統合パスがユーザーのメンタルモデルに合致するか」というものです。なぜなら、間違ったパスを選ぶと、ユーザーから制御を奪いすぎる（ユーザーが反復したかったのにプログラム的にしてしまう）か、あるいは制御が足りなさすぎる（ワンショットの結果を期待していたのにシートにしてしまう）UXが生まれるからです。

TL;DR

• imagePlaygroundSheet(isPresented:concept:sourceImage:onCompletion:onCancellation:)は、システムのImage Playgroundシートを提示するSwiftUIモディファイアです。ユーザーが反復し、選択された画像のURLがonCompletionを通じてアプリに渡されます（非オプショナルな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:)は優先スタイルと許可されたスタイルのリストを受け取ります。プライバシーに敏感なコンテキストや美学が固定されたコンテキストではこれらを使用してください。

2つのパス：シート vs プログラム的

2つの統合パスの選択は、誰が反復を制御するかに関わってきます。

シート統合は、ユーザーにシステムの完全な画像生成UIを渡します。ユーザーがプロンプトを入力し、バリエーションを選び、最終的な画像を選択します。アプリの仕事は、起点のコンセプトでシートを起動し、選ばれた結果を受け取ることです。次のような場合に使用します。

• ユーザーがアプリでは完全に予測できない創造的な意図を持っている場合
• インタラクションが創造的なワークフローの一部である場合（メッセージングアプリ、ノートアプリ、プロフィールカスタマイズフロー）
• ユーザーがコミットする前に反復することを期待している場合

プログラム的な統合は、アプリにモデルを直接渡します。アプリはコンセプトを供給し、システムUIを表示せずに画像を取得します。次のような場合に使用します。

• 生成が非インタラクティブなフローの一部である場合（システム生成のアバター、レシピカード用の決定論的なアセット、ワンショットのイラスト）
• アプリが特定の美学要件を持っている場合（常にイラストスタイル、常に1枚の画像）
• ユーザーに反復を見せるべきではなく、結果こそが重要な場合

2つのパスは基盤となるモデルを共有し、同じユーザーレベルの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インターフェース（プロンプト、スタイルピッカー、バリエーショングリッド、「Done」ボタン）が表示されます。アプリの役割は、起点のプロンプトを提供し、結果を受け取ることです。キャンセルは完了時のnil URLではなく、専用のonCancellationクロージャで発火します。onCompletionに渡されるURLは非オプショナルです。

単一の文字列よりも豊かな起点コンセプトを必要とするアプリのために、兄弟オーバーロードは[ImagePlaygroundConcept]を直接受け入れます。複数のコンセプトは構成できます。モデルはそれぞれを制約またはシグナルとして使用します。順序が重要です。テキストコンセプトはプロンプトを確立し、画像コンセプトは視覚的参照を確立し、ドローイングコンセプトはアウトラインを確立します。

ImagePlaygroundConceptのバリアント

AppleはいくつかのImagePlaygroundConceptコンストラクタを提供しています⁴。

.text(_:)。 短いテキスト記述。最も一般的な起点コンセプトです。

.image(_:)。 ソース画像（通常はURLまたはUIImage/NSImage）。モデルはこれをスタイルや構図の視覚的参照として使用します。

.drawing(_:)。 ドローイング、通常はPencilKitまたはカスタムドローイングサーフェスからのもの。モデルはストロークを構造的なヒントとして解釈します。

.extracted(from:title:)。 解析された画像から抽出されたコンセプト。2引数形式はソースURL（または画像タイプ）と抽出を記述するtitleを取ります。フレームワークはオンデバイス解析を使用して、参照から生成に適したコンセプトを導き出します。

コンセプトは構成できます。[text, image, extracted]をシートまたはImageCreatorに渡すことで、モデルは複数の制約を満たすことができます。適切なパターンは「有用な出力を生成するのに十分具体的で、モデルに余地があるくらい緩やか」というものです。1つか2つの具体的なコンセプトに加えて、オプションで参照画像を組み合わせます。

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スタイルで）は、生成呼び出しでスタイルを固定します。選択を公開したいアプリは、利用可能なケースにマッピングするスタイルピッカーを表示します。

パーソナライゼーションとポリシーモディファイア

2つのSwiftUIモディファイアにより、アプリはコンテキスト内でImage Playgroundの動作を制約できます⁶。

.imagePlaygroundPersonalizationPolicy(_:)。 ImagePlaygroundPersonalizationPolicy値を取ります。.automatic（システムデフォルト）、.enabled（明示的に許可）、または.disabled（連絡先や写真などの個人コンテンツをシステムが参照することを禁止）です。プライバシーに敏感なコンテキスト（医療、金融、匿名通信）のアプリでは.disabledを使用してください。

.imagePlaygroundGenerationStyle(_:in:)。 優先スタイルと許可されたスタイルの配列を取ります。ユーザーのスタイルピッカー（表示されている場合）は許可されたリストに制約され、優先スタイルがデフォルトになります。アプリの美学が利用可能なスタイルの制約や固定を必要とする場合に使用してください。

両方のモディファイアは、システムレベルのApple Intelligence設定を最低基準として尊重します。アプリはシステムが無効にした機能をオーバーライドできず、さらに制約することしかできません。

よくある失敗

Image Playground統合のログから3つのパターンを紹介します。

ImageCreator()をイニシャライザのエラーをキャッチせずに呼び出すこと。 Apple Intelligence非対応のデバイスでは、クリエイターは初期化時にスローします。tryしてキャッチしないアプリは、ユーザーに混乱したエラーを表示します。修正方法：ImageCreator()をtryでラップし、availableStylesを確認し、失敗時にフォールバックパスを提供します（プレースホルダを表示する、設定でApple Intelligenceを有効化するようユーザーを促す、または機能を完全に非表示にする）。

統合パスとユースケースのミスマッチ。 ImageCreatorを使用するプロフィールアバタージェネレーターは、ユーザーが調整できないワンショットアバターを生成します。シートを使用するワンショットアバタージェネレーターは摩擦を増やします。パスをユーザーの期待に合わせてください。反復したいならシート、結果が欲しいならプログラム的に。

システムのポリシーフロアを無視すること。 システムのApple Intelligence設定をバイパスしようとするアプリ（例：ユーザーがグローバルに無効にしたコンテキストで画像を生成する）は、ポリシーエラーに遭遇します。修正方法：システム構成を尊重し、Apple Intelligenceが無効になっているときはサイレントな失敗ではなく意味のあるエラーを表示してください。

このパターンがApple Intelligenceアプリにとって意味すること

3つのテイクアウェイがあります。

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、ランタイム vs ツーリング LLM の区別、3つのサーフェス、単一の真実の源パターン、2つの MCP サーバー、Apple開発のためのフック、Live Activities、watchOSランタイム、SwiftUIの内部、RealityKitの空間メンタルモデル、SwiftDataのスキーマ規律、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 Seriesにあります。AIエージェントを伴うiOSの広範なコンテキストについては、iOS Agent Developmentガイドをご覧ください。

FAQ

Apple Intelligenceが利用できない場合に対処する必要がありますか？

はい。Image Playgroundは、機能が有効になっているApple Intelligence対応デバイス（iPhone 15 Pro以降、Mシリーズ Mac）が必要です。サポートされていないデバイスでは、シートは表示されず、ImageCreator()は初期化時にスローします。チェックパターン：ImageCreator()をtryでラップし、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 が生成したプロンプトを画像生成に供給する）は、2つの API を順番に構成します。

参考文献