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

Update (11. Juni 2026): Apple stellt ImageCreator ein, den programmatischen Weg, den dieser Beitrag behandelt. Ab iOS 27, iPadOS 27, macOS 27 und visionOS 27 funktioniert er nicht mehr. Die Sheet-basierten APIs, die im restlichen Beitrag behandelt werden, bleiben der unterstützte Weg. Lesen Sie den vollständigen Beitrag zur Einstellung für den Zeitplan und die Migration.

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

Der Beitrag arbeitet die API anhand von Apples Dokumentation durch. Der Leitgedanke lautet „welcher Integrationsweg zum mentalen Modell des Benutzers passt”, denn die Wahl des falschen Wegs erzeugt eine UX, die dem Benutzer entweder zu viel Kontrolle entzieht (programmatisch, obwohl der Benutzer iterieren wollte) oder zu wenig (Sheet, obwohl der Benutzer ein einmaliges Ergebnis erwartete).

TL;DR

• imagePlaygroundSheet(isPresented:concept:sourceImage:onCompletion:onCancellation:) ist der SwiftUI-Modifier, der das System-Sheet von Image Playground präsentiert. Der Benutzer iteriert; die App empfängt 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

Die Entscheidung zwischen den beiden Integrationswegen dreht sich darum, wer die Iteration kontrolliert.

Die Sheet-Integration übergibt dem Benutzer die vollständige systemeigene UI zur Bildgenerierung. Der Benutzer tippt Prompts ein, wählt Varianten 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 zu empfangen. Verwenden Sie dies, wenn:

• 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 Notizen-App, ein Ablauf zur Profilanpassung).
• Der Benutzer erwartet, vor der Festlegung zu iterieren.

Die programmatische Integration gibt der App das Modell direkt in die Hand. Die App liefert Konzepte und erhält Bilder zurück, ohne die System-UI anzuzeigen. Verwenden Sie dies, wenn:

• Die Generierung Teil eines nicht-interaktiven Ablaufs ist (ein systemgenerierter Avatar, ein deterministisches Asset für eine Rezeptkarte, eine einmalige Illustration).
• Die App eine konkrete ästhetische Anforderung hat (immer Illustrationsstil, immer ein Bild).
• Der Benutzer die Iteration nicht sehen soll; nur das Ergebnis zählt für ihn.

Die beiden Wege teilen sich das zugrunde liegende 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 5 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. Der Benutzer sieht Apples Standard-Oberfläche von Image Playground (Prompts, Stilauswahl, Variantenraster, „Done”-Schaltfläche). Die Rolle der App besteht darin, den Ausgangs-Prompt bereitzustellen und das Ergebnis zu empfangen. Ein Abbruch löst die dedizierte onCancellation-Closure aus, statt einer nil-URL beim Abschluss; die an onCompletion übergebene URL ist nicht-optional.

Für Apps, die reichhaltigere Ausgangskonzepte als eine einzelne Zeichenkette wünschen, akzeptieren verwandte Überladungen [ImagePlaygroundConcept] direkt. Mehrere Konzepte lassen sich kombinieren: Das Modell verwendet jedes als Einschränkung oder Signal. Die Reihenfolge ist entscheidend: 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 häufigste 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 eigenen Zeichenfläche. Das Modell interpretiert die Striche als strukturellen Hinweis.

.extracted(from:title:). Aus einem analysierten Bild extrahierte Konzepte. Die Form mit zwei Argumenten nimmt eine Quell-URL (oder einen Bildtyp) und einen title entgegen, der die Extraktion beschreibt. Das Framework nutzt eine geräteinterne Analyse, um aus der Referenz ein für die Generierung geeignetes Konzept abzuleiten.

Konzepte lassen sich kombinieren: Die Übergabe von [text, image, extracted] an das Sheet oder an ImageCreator ermöglicht es dem Modell, mehrere Einschränkungen zu erfüllen. Das richtige Muster lautet „konkret genug, um nützliche Ausgaben zu erzeugen, locker genug, dass das Modell Spielraum hat”: ein oder zwei konkrete Konzepte plus optionale Referenzbilder.

ImageCreator: Der programmatische Weg

[Update: Apple hat ImageCreator zum 11. Juni 2026 eingestellt; siehe den Beitrag zur Einstellung für den iOS-27-Zeitplan und die Migration. Der folgende Abschnitt bleibt als historische Dokumentation der API erhalten.]

ImageCreator ist die programmatische API für Apps, die eine 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 ermöglicht es Apps, Teilergebnisse anzuzeigen (die schrittweise Verfeinerung des Modells) oder auf das endgültige Bild zu warten. Der Parameter limit: begrenzt die Anzahl der angeforderten Bilder; Apple gibt je nach Richtlinie oder Gerätezustand möglicherweise weniger zurück.

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

ImagePlaygroundStyle-Varianten

Der Stilparameter schränkt die visuelle Ästhetik ein⁵:

• .animation. Apples Stil für animierte Figuren (abgerundete Formen, kräftige Umrisse, vereinfachte Merkmale). Nützlich für Avatare, Maskottchen, freundliche UI-Illustrationen.
• .illustration. Flacher Illustrationsstil mit vektorartiger Ästhetik. Nützlich für Infografiken, Rezeptkarten, konzeptionelle Bilder.
• .sketch. Bleistiftskizzen-Stil (in späteren Releases hinzugefügt). Nützlich für Notiz-Apps, Journaling, handgezeichnete Ästhetik.

Apps, die eine durchgängige Ästhetik über generierte 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 möchten, zeigen eine Stilauswahl, 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 (Systemstandard), .enabled (ausdrücklich erlauben) oder .disabled (dem System verbieten, auf persönliche Inhalte wie Kontakte/Fotos zuzugreifen). 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 des Benutzers (sofern sichtbar) wird auf die erlaubte Liste beschränkt, und der bevorzugte Stil ist die Voreinstellung. Verwenden Sie dies, wenn die Ästhetik der App es erfordert, die verfügbaren Stile einzuschränken oder festzulegen.

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

Häufige Fehler

Drei Muster aus Protokollen zur Image-Playground-Integration:

ImageCreator() aufrufen, ohne den Initializer-Fehler abzufangen. Auf Geräten ohne Apple Intelligence wirft der Creator bei der Initialisierung einen Fehler. Apps, die kein try und kein Abfangen verwenden, präsentieren dem Benutzer einen verwirrenden Fehler. Lösung: ImageCreator() in try kapseln, availableStyles prüfen und bei einem Fehlschlag einen Ausweichweg bereitstellen (einen Platzhalter anzeigen, den Benutzer auffordern, Apple Intelligence in den Einstellungen zu aktivieren, oder die Funktion vollständig ausblenden).

Den Integrationsweg nicht zum Anwendungsfall passend wählen. Ein Generator für Profil-Avatare, der ImageCreator verwendet, erzeugt einen einmaligen Avatar, den der Benutzer nicht anpassen kann; ein Generator für einmalige Avatare, der das Sheet verwendet, fügt Reibung hinzu. Passen Sie den Weg an die Erwartung des Benutzers an: Will er iterieren, dann das Sheet; will er ein Ergebnis, dann programmatisch.

Die Richtlinien-Untergrenze des Systems ignorieren. Apps, die versuchen, die System-Einstellungen von Apple Intelligence zu umgehen (z. B. Bilder in einem Kontext zu generieren, den der Benutzer global deaktiviert hat), stoßen auf Richtlinienfehler. Lösung: Respektieren Sie die Systemkonfiguration; geben Sie aussagekräftige Fehler aus, 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 des Benutzers. Sheet für kreative Iteration; programmatisch für einmalige Generierung in nicht-interaktiven Abläufen. Der Preis einer falschen Wahl ist reale UX-Reibung.

2. Schränken Sie Stil und Personalisierung bewusst ein. Eine Messaging-App, die einen einheitlichen Avatar-Stil wünscht, übergibt einen einzigen erlaubten Stil an .imagePlaygroundGenerationStyle(_:in:). Eine datenschutzorientierte Journaling-App setzt .imagePlaygroundPersonalizationPolicy(.disabled). Die Voreinstellungen sind freizügig (.automatic); bewusste Einschränkungen lassen die Funktion durchdacht wirken.

3. Prüfen Sie immer die availableStyles von ImageCreator() (oder fangen Sie den Initializer-Fehler ab) und halten Sie einen Ausweichweg bereit. Apple Intelligence erfordert bestimmte Hardware (iPhone 15 Pro und neuer, M-Series-Macs) plus eine ausdrückliche Zustimmung des Benutzers. Apps, die ohne Verfügbarkeitsprüfungen auf Image Playground angewiesen sind, schlagen auf älteren Geräten und auf Geräten mit deaktiviertem Apple Intelligence verwirrend fehl.

Der vollständige Apple-Ecosystem-Cluster: typisierte App Intents; MCP-Server; die Routing-Frage; Foundation Models; die Unterscheidung zwischen Laufzeit- 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-Laufzeit; SwiftUI-Interna; RealityKits räumliches mentales Modell; SwiftData-Schemadisziplin; Liquid-Glass-Muster; Multi-Plattform-Auslieferung; die Plattform-Matrix; Vision-Framework; Symbol Effects; Core-ML-Inferenz; Writing Tools API; Swift Testing; Privacy Manifest; Barrierefreiheit als Plattform; SF-Pro-Typografie; räumliche visionOS-Muster; Speech-Framework; SwiftData-Migrationen; tvOS-Focus-Engine; @Observable-Interna; SwiftUI-Layout-Protokoll; eigene SF Symbols; AVFoundation HDR; watchOS-Workout-Lebenszyklus; App Intents 2.0 in iOS 26; worüber ich mich weigere zu schreiben. Der Hub befindet sich in der Apple Ecosystem Series. Für einen breiteren Kontext zu iOS mit KI-Agenten siehe den iOS Agent Development Guide.

FAQ

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

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

Kann ich die UI des Sheets anpassen?

Nein. Das Sheet wird vom System gesteuert. Die App liefert das Ausgangskonzept und empfängt das Ergebnis; alles dazwischen ist Apples UI. Wenn Sie eine eigene UI benötigen, verwenden Sie die programmatische ImageCreator-API und bauen Sie Ihre eigene Iterationsoberfläche darum herum.

Was geschieht mit generierten Bildern, wenn der Benutzer das Sheet schließt?

Die imagePlaygroundSheet-Überladung mit 5 Parametern stellt separate onCompletion- und onCancellation-Closures bereit. onCompletion wird mit einer nicht-optionalen URL ausgelöst, wenn der Benutzer ein Bild auswählt; onCancellation wird ausgelöst, wenn der Benutzer ohne Auswahl schließt. Die temporären Bilddaten werden vom System bereinigt; 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 erfordert für sich genommen keinen Zugriff auf die Fotomediathek. Wenn der Benutzer innerhalb des Sheets auf seine Fotomediathek verweist (beim Durchsuchen nach einem Bild, das als Konzept dienen soll), behandelt das Sheet die Berechtigungsabfrage intern. Apps müssen für die Image-Playground-Integration nicht vorab eine Foto-Berechtigung anfordern.

Kann ich Bilder im Hintergrund generieren?

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

Wie verhält sich dies zum Foundation-Models-LLM?

Das Modell von Image Playground ist getrennt vom geräteinternen Foundation-Models-LLM (behandelt in Foundation Models on-device LLM). Beide teilen sich die Infrastruktur des Apple-Intelligence-Frameworks, nutzen aber unterschiedliche spezialisierte Modelle. Apps, die sie kombinieren (LLM-generierte Prompts, die in die Bildgenerierung einfließen), verketten die beiden APIs nacheinander.

Quellenangaben