Image Playground API: SwiftUI Sheet, programmatischer Image Creator und Stilkontrolle

Image Playground von Apple Intelligence stellt Apps zwei Integrationswege bereit. Der SwiftUI-Modifier imagePlaygroundSheet() präsentiert die systemeigene Benutzeroberfläche zur Bilderzeugung; die Entwicklerin oder der Entwickler übergibt ein Ausgangskonzept (Text oder Bild), die Benutzerin oder der Benutzer iteriert innerhalb des Sheets, und das Ergebnis wird an die App zurückgegeben. Der ImageCreator API führt dieselbe Generierungspipeline programmatisch aus: Die Entwicklerin oder der Entwickler liefert ein Array von ImagePlaygroundConcept-Objekten plus einen Stil, und das Framework gibt erzeugte Bilder zurück, ohne eine UI anzuzeigen¹. Die beiden Wege zielen auf unterschiedliche Anwendungsfälle ab. Die Sheet-Integration ist richtig, wenn die Benutzerin oder der Benutzer iterieren soll; die programmatische Integration ist richtig, wenn die App eine spezifische Generierungsanfrage hat und das Ergebnis direkt anzeigt.

Der Beitrag arbeitet sich anhand der Apple-Dokumentation durch den API. Der Rahmen lautet: „Welcher Integrationsweg passt zum mentalen Modell der Benutzerin oder des Benutzers?”, denn die Wahl des falschen Wegs erzeugt eine UX, die der Benutzerin oder dem Benutzer entweder zu viel Kontrolle nimmt (programmatisch, wenn sie iterieren wollte) oder zu wenig (Sheet, wenn ein einmaliges Ergebnis erwartet wurde).

TL;DR

• imagePlaygroundSheet(isPresented:concept:sourceImage:onCompletion:onCancellation:) ist der SwiftUI-Modifier, der das System-Sheet von Image Playground präsentiert. Die Benutzerin oder der Benutzer iteriert; die App erhält die URL des gewählten Bildes über onCompletion (nicht-optionale URL); ein Abbruch löst onCancellation aus².
• ImageCreator().images(for: [ImagePlaygroundConcept], style: ImagePlaygroundStyle, limit: Int) ist der programmatische Weg (iOS 18.4+). Die Methode gibt eine AsyncSequence von ImageCreator.CreatedImage-Ergebnissen zurück³.
• ImagePlaygroundConcept trägt die Eingabe, die das Modell verwendet: Textbeschreibungen (.text("a watercolor of a cat")), Quellbilder (.image(...)), Zeichnungen (.drawing(...)) oder aus einer Referenz extrahierte Konzepte (.extracted(from:title:)).
• ImagePlaygroundStyle wählt die visuelle Ästhetik. Apps fragen ImageCreator().availableStyles ab, um zu ermitteln, welche Fälle das Gerät unterstützt.
• .imagePlaygroundPersonalizationPolicy(_:) akzeptiert .automatic, .enabled oder .disabled. .imagePlaygroundGenerationStyle(_:in:) nimmt einen bevorzugten Stil und eine Liste erlaubter Stile entgegen. Verwenden Sie diese für datenschutzsensible oder ästhetisch festgelegte Kontexte.

Die zwei Wege: Sheet vs. programmatisch

Bei der Entscheidung zwischen den beiden Integrationswegen geht es darum, wer die Iteration steuert.

Sheet-Integration übergibt der Benutzerin oder dem Benutzer die vollständige System-UI zur Bilderzeugung. Die Benutzerin oder der Benutzer gibt Prompts ein, wählt Variationen aus und entscheidet sich für das endgültige Bild. Die Aufgabe der App besteht darin, das Sheet mit einem Ausgangskonzept zu starten und das gewählte Ergebnis entgegenzunehmen. Verwenden Sie diesen Weg, wenn:

• Die Benutzerin oder der Benutzer eine kreative Absicht hat, die die App nicht vollständig vorhersagen kann.
• Die Interaktion Teil eines kreativen Workflows ist (eine Messaging-App, eine Notiz-App, ein Profilanpassungs-Flow).
• Die Benutzerin oder der Benutzer erwartet, vor der Festlegung zu iterieren.

Programmatische Integration stellt der App das Modell direkt zur Verfügung. Die App liefert Konzepte und erhält Bilder zurück, ohne die System-UI anzuzeigen. Verwenden Sie diesen Weg, wenn:

• Die Generierung Teil eines nicht-interaktiven Flows ist (ein systemerzeugter Avatar, ein deterministisches Asset für eine Rezeptkarte, eine einmalige Illustration).
• Die App eine spezifische ästhetische Anforderung hat (immer Illustrationsstil, immer ein Bild).
• Die Benutzerin oder der Benutzer die Iteration nicht sehen soll; das Ergebnis ist das, worauf es ankommt.

Die beiden Wege teilen sich das zugrundeliegende Modell und respektieren dieselbe nutzerseitige Apple-Intelligence-Konfiguration. Die Wahl ist rein eine Frage der UX.

Das SwiftUI-Sheet

imagePlaygroundSheet wird in mehreren Überladungsvarianten auf View ausgeliefert. Die kanonische Form mit fünf Parametern nimmt ein Ausgangskonzept, eine optionale Quellbildreferenz sowie Completion- und Cancellation-Handler entgegen²:

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

Die UX des Sheets wird vom System gesteuert. Die Benutzerin oder der Benutzer sieht die Standard-Image-Playground-Oberfläche von Apple (Prompts, Stilauswahl, Variationsraster, Schaltfläche „Fertig”). Die Rolle der App besteht darin, den Ausgangs-Prompt bereitzustellen und das Ergebnis entgegenzunehmen. Ein Abbruch löst den dedizierten onCancellation-Closure aus statt einer nil-URL bei der Vervollständigung; die an onCompletion übergebene URL ist nicht-optional.

Für Apps, die reichhaltigere Ausgangskonzepte als einen einzelnen String wünschen, akzeptieren Schwester-Überladungen [ImagePlaygroundConcept] direkt. Mehrere Konzepte werden komponiert: Das Modell verwendet jedes als Beschränkung oder Signal. Die Reihenfolge ist wichtig: Textkonzepte legen den Prompt fest; Bildkonzepte legen eine visuelle Referenz fest; Zeichnungskonzepte legen einen Umriss fest.

ImagePlaygroundConcept-Varianten

Apple liefert mehrere ImagePlaygroundConcept-Konstruktoren aus⁴:

.text(_:). Eine kurze Textbeschreibung. Das gebräuchlichste Ausgangskonzept.

.image(_:). Ein Quellbild (typischerweise eine URL oder ein UIImage/NSImage). Das Modell verwendet es als visuelle Referenz für Stil oder Komposition.

.drawing(_:). Eine Zeichnung, typischerweise aus PencilKit oder einer benutzerdefinierten Zeichenfläche. Das Modell interpretiert die Striche als strukturellen Hinweis.

.extracted(from:title:). Konzepte, die aus einem analysierten Bild extrahiert werden. Die Form mit zwei Argumenten nimmt eine Quell-URL (oder einen Bildtyp) und einen title, der die Extraktion beschreibt. Das Framework verwendet On-Device-Analyse, um aus der Referenz ein für die Generierung geeignetes Konzept abzuleiten.

Konzepte werden komponiert: Wird [text, image, extracted] an das Sheet oder an ImageCreator übergeben, kann das Modell mehrere Beschränkungen erfüllen. Das richtige Muster lautet: „spezifisch genug, um nützliche Ausgaben zu erzeugen, aber locker genug, dass das Modell Spielraum hat” — ein oder zwei konkrete Konzepte plus optionales Referenzmaterial.

ImageCreator: Der programmatische Weg

ImageCreator ist der programmatische API für Apps, die Generierung ohne UI wünschen³:

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

Die Methode images(for:style:limit:) gibt eine AsyncSequence von ImageCreator.CreatedImage-Ergebnissen zurück. Das asynchrone Streaming-Modell erlaubt Apps, Teilergebnisse anzuzeigen (die progressive Verfeinerung des Modells) oder auf das endgültige Bild zu warten. Der Parameter limit: begrenzt die Anzahl der angeforderten Bilder; Apple kann basierend auf Richtlinien oder Gerätestatus weniger zurückgeben.

Der programmatische Weg setzt iOS 18.4+ voraus und erfordert ein Apple-Intelligence-fähiges Gerät mit aktivierter Funktion. Das Muster zur Verfügbarkeitsprüfung: Konstruieren Sie ImageCreator innerhalb von try und lesen Sie dann availableStyles. Eine leere availableStyles-Sammlung (oder ein geworfener Initializer) signalisiert, dass die Generierung auf dem aktuellen Gerät nicht verfügbar ist; Apps weichen auf einen nicht-generativen Pfad aus (Asset-Bibliothek, vom Benutzer hochgeladenes Bild usw.).

ImagePlaygroundStyle-Varianten

Der Stilparameter beschränkt die visuelle Ästhetik⁵:

• .animation. Apples Stil animierter Charaktere (abgerundete Formen, kräftige Konturen, vereinfachte Gesichtszüge). Nützlich für Avatare, Maskottchen, freundliche UI-Illustrationen.
• .illustration. Flacher Illustrationsstil mit vektorartiger Ästhetik. Nützlich für Infografiken, Rezeptkarten, konzeptuelle Bildwelten.
• .sketch. Bleistiftskizzenstil (in späteren Releases hinzugefügt). Nützlich für Notiz-Apps, Tagebuch-Apps, handgezeichnete Ästhetiken.

Apps, die eine konsistente Ästhetik über erzeugte Bilder hinweg wünschen (jeder Avatar im .animation-Stil, jede Rezeptkarte im .illustration-Stil), legen den Stil in ihren Generierungsaufrufen fest; Apps, die die Wahl freigeben wollen, bieten eine Stilauswahl an, die auf die verfügbaren Fälle abgebildet wird.

Personalisierungs- und Richtlinien-Modifier

Zwei SwiftUI-Modifier ermöglichen es Apps, das Verhalten von Image Playground in ihrem Kontext einzuschränken⁶:

.imagePlaygroundPersonalizationPolicy(_:). Nimmt einen ImagePlaygroundPersonalizationPolicy-Wert entgegen: .automatic (Systemvorgabe), .enabled (explizit erlauben) oder .disabled (verhindert, dass das System auf persönliche Inhalte wie Kontakte/Fotos zugreift). Verwenden Sie .disabled für Apps in datenschutzsensiblen Kontexten (Medizin, Finanzen, anonyme Kommunikation).

.imagePlaygroundGenerationStyle(_:in:). Nimmt einen bevorzugten Stil und ein Array erlaubter Stile entgegen. Die Stilauswahl der Benutzerin oder des Benutzers (sofern sichtbar) wird auf die erlaubte Liste beschränkt, und der bevorzugte Stil ist die Vorgabe. Verwenden Sie dies, wenn die Ästhetik der App es erfordert, die verfügbaren Stile zu beschränken oder zu fixieren.

Beide Modifier respektieren die systemweite Apple-Intelligence-Konfiguration als Untergrenze. Apps können keine Funktionen überschreiben, die das System deaktiviert hat; sie können nur weiter einschränken.

Häufige Fehler

Drei Muster aus Image-Playground-Integrationsprotokollen:

Aufruf von ImageCreator() ohne Abfangen des Initializer-Fehlers. Auf Geräten ohne Apple Intelligence wirft der Creator bei der Initialisierung einen Fehler. Apps, die kein try und kein Catch verwenden, zeigen der Benutzerin oder dem Benutzer einen verwirrenden Fehler. Lösung: Umschließen Sie ImageCreator() mit try, prüfen Sie availableStyles und stellen Sie bei Fehlschlag einen Fallback-Pfad bereit (Platzhalter anzeigen, die Benutzerin oder den Benutzer auffordern, Apple Intelligence in den Einstellungen zu aktivieren, oder die Funktion vollständig ausblenden).

Unpassende Zuordnung des Integrationswegs zum Anwendungsfall. Ein Profilbild-Generator, der ImageCreator verwendet, erzeugt einen einmaligen Avatar, den die Benutzerin oder der Benutzer nicht anpassen kann; ein Einmal-Avatar-Generator, der das Sheet verwendet, fügt Reibung hinzu. Stimmen Sie den Weg auf die Erwartung der Benutzerin oder des Benutzers ab: Wenn iteriert werden soll, Sheet; wenn ein Ergebnis gewünscht wird, programmatisch.

Ignorieren der System-Richtlinien-Untergrenze. Apps, die versuchen, die System-Apple-Intelligence-Einstellungen zu umgehen (z. B. Bilder in einem Kontext zu erzeugen, den die Benutzerin oder der Benutzer global deaktiviert hat), stoßen auf Richtlinienfehler. Lösung: Respektieren Sie die Systemkonfiguration; zeigen Sie aussagekräftige Fehler an, wenn Apple Intelligence deaktiviert ist, statt eines stillen Fehlschlags.

Was dieses Muster für Apple-Intelligence-Apps bedeutet

Drei Erkenntnisse.

1. Wählen Sie den Integrationsweg nach dem mentalen Modell der Benutzerin oder des Benutzers. Sheet für kreative Iteration; programmatisch für einmalige Generierung in nicht-interaktiven Flows. Die Kosten einer falschen Wahl sind reale UX-Reibung.

2. Beschränken Sie Stil und Personalisierung bewusst. Eine Messaging-App, die einen konsistenten Avatar-Stil wünscht, übergibt einen einzelnen erlaubten Stil an .imagePlaygroundGenerationStyle(_:in:). Eine datenschutzorientierte Tagebuch-App setzt .imagePlaygroundPersonalizationPolicy(.disabled). Die Vorgaben sind freizügig (.automatic); bewusste Beschränkungen lassen die Funktion absichtsvoll wirken.

3. Prüfen Sie immer ImageCreator()s availableStyles (oder fangen Sie den Initializer-Fehler ab) und halten Sie einen Fallback bereit. Apple Intelligence erfordert spezifische Hardware (iPhone 15 Pro und später, M-Series-Macs) plus Opt-in der Benutzerin oder des Benutzers. Apps, die ohne Verfügbarkeitsprüfungen auf Image Playground angewiesen sind, scheitern auf älteren Geräten und auf Geräten mit deaktivierter Apple Intelligence verwirrend.

Der vollständige Apple-Ecosystem-Cluster: typisierte App Intents; MCP-Server; die Routing-Frage; Foundation Models; die Unterscheidung zwischen Runtime und Tooling-LLM; drei Oberflächen; das Single-Source-of-Truth-Muster; zwei MCP-Server; Hooks für die Apple-Entwicklung; Live Activities; die watchOS-Runtime; SwiftUI-Internals; RealityKits räumliches mentales Modell; SwiftData-Schema-Disziplin; Liquid-Glass-Muster; Multi-Plattform-Auslieferung; die Plattform-Matrix; Vision-Framework; Symbol Effects; Core-ML-Inferenz; Writing Tools API; Swift Testing; Privacy Manifest; Accessibility als Plattform; SF-Pro-Typografie; visionOS-räumliche Muster; Speech-Framework; SwiftData-Migrationen; tvOS-Focus-Engine; @Observable-Internals; SwiftUI-Layout-Protokoll; benutzerdefinierte SF Symbols; AVFoundation HDR; watchOS-Workout-Lebenszyklus; App Intents 2.0 in iOS 26; worüber ich nicht schreibe. Der Hub liegt in der Apple Ecosystem Series. Für breiteren Kontext zu iOS mit AI-Agenten siehe den iOS Agent Development Guide.

FAQ

Muss ich behandeln, dass Apple Intelligence nicht verfügbar ist?

Ja. Image Playground erfordert ein Apple-Intelligence-fähiges Gerät (iPhone 15 Pro und später, M-Series-Macs) mit aktivierter Funktion. Auf nicht unterstützten Geräten wird das Sheet nicht angezeigt, und ImageCreator() wirft bei der Initialisierung einen Fehler. Das Prüfmuster: Umschließen Sie ImageCreator() mit try und prüfen Sie availableStyles; eine leere Sammlung oder ein geworfener Initializer signalisiert, dass die Generierung nicht verfügbar ist. Stellen Sie für nicht unterstützte Benutzerinnen und Benutzer einen nicht-generativen Fallback bereit.

Kann ich die UI des Sheets anpassen?

Nein. Das Sheet wird vom System gesteuert. Die App liefert das Ausgangskonzept und erhält das Ergebnis; alles dazwischen ist Apples UI. Wenn Sie eine eigene UI benötigen, verwenden Sie den programmatischen ImageCreator API und bauen Sie Ihre eigene Iterationsoberfläche darum herum auf.

Was passiert mit erzeugten Bildern, wenn die Benutzerin oder der Benutzer das Sheet schließt?

Die 5-Parameter-Überladung von imagePlaygroundSheet stellt separate onCompletion- und onCancellation-Closures bereit. onCompletion feuert mit einer nicht-optionalen URL, wenn die Benutzerin oder der Benutzer ein Bild auswählt; onCancellation feuert, wenn ohne Auswahl geschlossen wird. Die temporären Bilddaten werden vom System aufgeräumt; Apps, die ein Bild behalten möchten, müssen es im Completion-Handler in ihren eigenen Speicher sichern.

Wie interagiert Image Playground mit Foto-Berechtigungen?

Das Sheet selbst benötigt keinen Zugriff auf die Fotomediathek. Wenn die Benutzerin oder der Benutzer innerhalb des Sheets auf die Fotomediathek zugreift (Durchsuchen nach einem Bild zur Verwendung als Konzept), behandelt das Sheet die Berechtigungsabfrage intern. Apps müssen für die Image-Playground-Integration nicht im Voraus eine Foto-Berechtigung anfordern.

Kann ich Bilder im Hintergrund erzeugen?

ImageCreator läuft im Vordergrund; das Framework verwaltet die Systemressourcen für die Generierung. Apps, die Bildgenerierung im Hintergrund wünschen, müssen ihre App im Vordergrund halten (oder in einem Sitzungstyp, der fortgesetzte Ausführung erlaubt, wie eine Workout-Sitzung, die in watchOS-Workout-Lebenszyklus behandelt wird).

Wie verhält sich das zur Foundation-Models-LLM?

Das Modell von Image Playground ist getrennt von der Foundation-Models-On-Device-LLM (behandelt in Foundation Models on-device LLM). Beide teilen sich die Apple-Intelligence-Framework-Infrastruktur, verwenden aber unterschiedliche Spezialmodelle. Apps, die sie kombinieren (LLM-erzeugte Prompts, die in die Bildgenerierung einfließen), komponieren die beiden APIs in Folge.

References