Image Playground API: arkusz SwiftUI, programowy kreator obrazów i kontrola stylu

Aktualizacja (11 czerwca 2026): Apple wycofuje ImageCreator, czyli programową ścieżkę opisaną w tym wpisie. Przestaje ona działać w iOS 27, iPadOS 27, macOS 27 i visionOS 27. API oparte na arkuszu, omówione w pozostałej części wpisu, pozostaje obsługiwaną ścieżką. Pełny harmonogram i informacje o migracji znajdują się we wpisie o wycofaniu.

Image Playground z Apple Intelligence udostępnia aplikacjom dwie ścieżki integracji. Modyfikator imagePlaygroundSheet() w SwiftUI prezentuje systemowy interfejs generowania obrazów widoczny dla użytkownika; deweloper przekazuje początkową koncepcję (tekst lub obraz), użytkownik iteruje wewnątrz arkusza, a wynik wraca do aplikacji. API ImageCreator uruchamia ten sam potok generowania programowo: deweloper dostarcza tablicę obiektów ImagePlaygroundConcept oraz styl, a framework zwraca wygenerowane obrazy bez wyświetlania UI¹. Te dwie ścieżki są przeznaczone do różnych zastosowań. Integracja przez arkusz jest właściwa, gdy to użytkownik ma iterować; integracja programowa jest właściwa, gdy aplikacja ma konkretne żądanie generowania i bezpośrednio prezentuje wynik.

Wpis omawia API w odniesieniu do dokumentacji Apple. Ramą jest pytanie „która ścieżka integracji odpowiada modelowi mentalnemu użytkownika”, ponieważ wybór złej ścieżki prowadzi do UX, które albo odbiera użytkownikowi zbyt dużo kontroli (programowa, gdy użytkownik chciał iterować), albo zbyt mało (arkusz, gdy użytkownik oczekiwał jednorazowego wyniku).

TL;DR

• imagePlaygroundSheet(isPresented:concept:sourceImage:onCompletion:onCancellation:) to modyfikator SwiftUI, który prezentuje systemowy arkusz Image Playground. Użytkownik iteruje; aplikacja otrzymuje adres URL wybranego obrazu przez onCompletion (URL nie jest opcjonalny); anulowanie wyzwala onCancellation².
• ImageCreator().images(for: [ImagePlaygroundConcept], style: ImagePlaygroundStyle, limit: Int) to ścieżka programowa (iOS 18.4+). Metoda zwraca AsyncSequence wyników ImageCreator.CreatedImage³.
• ImagePlaygroundConcept niesie dane wejściowe, których używa model: opisy tekstowe (.text("a watercolor of a cat")), obrazy źródłowe (.image(...)), rysunki (.drawing(...)) lub koncepcje wyodrębnione z materiału referencyjnego (.extracted(from:title:)).
• ImagePlaygroundStyle wybiera estetykę wizualną. Aplikacje odpytują ImageCreator().availableStyles, aby ustalić, które przypadki obsługuje dane urządzenie.
• .imagePlaygroundPersonalizationPolicy(_:) przyjmuje .automatic, .enabled lub .disabled. .imagePlaygroundGenerationStyle(_:in:) przyjmuje preferowany styl oraz listę dozwolonych stylów. Warto z nich korzystać w kontekstach wrażliwych na prywatność lub z zablokowaną estetyką.

Dwie ścieżki: arkusz kontra ścieżka programowa

Decyzja między dwiema ścieżkami integracji dotyczy tego, kto kontroluje iterację.

Integracja przez arkusz oddaje użytkownikowi pełny systemowy interfejs generowania obrazów. Użytkownik wpisuje prompty, wybiera warianty i wskazuje finalny obraz. Zadaniem aplikacji jest uruchomienie arkusza z początkową koncepcją i odebranie wybranego wyniku. Należy jej używać, gdy:

• Użytkownik ma intencję twórczą, której aplikacja nie jest w stanie w pełni przewidzieć.
• Interakcja stanowi część przepływu twórczego (aplikacja do wiadomości, aplikacja do notatek, przepływ personalizacji profilu).
• Użytkownik oczekuje, że będzie iterować, zanim podejmie decyzję.

Integracja programowa daje aplikacji bezpośredni dostęp do modelu. Aplikacja dostarcza koncepcje i odbiera obrazy, bez wyświetlania systemowego UI. Należy jej używać, gdy:

• Generowanie jest częścią przepływu nieinteraktywnego (awatar generowany przez system, deterministyczny zasób dla karty z przepisem, jednorazowa ilustracja).
• Aplikacja ma konkretne wymaganie estetyczne (zawsze styl ilustracji, zawsze jeden obraz).
• Użytkownik nie powinien widzieć iteracji; liczy się dla niego wynik.

Obie ścieżki współdzielą ten sam model bazowy i respektują tę samą konfigurację Apple Intelligence na poziomie użytkownika. Wybór dotyczy wyłącznie UX.

Arkusz SwiftUI

imagePlaygroundSheet występuje w kilku wariantach przeciążenia na typie View. Kanoniczna forma z pięcioma parametrami przyjmuje początkową koncepcję, opcjonalne odwołanie do obrazu źródłowego oraz procedury obsługi ukończenia i anulowania²:

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 arkusza jest kontrolowane przez system. Użytkownik widzi standardowy interfejs Image Playground od Apple (prompty, wybór stylu, siatkę wariantów, przycisk „Done”). Rolą aplikacji jest dostarczenie początkowego promptu i odebranie wyniku. Anulowanie wyzwala dedykowaną domknięcie onCancellation, a nie wartość nil URL przy ukończeniu; URL przekazany do onCompletion nie jest opcjonalny.

W przypadku aplikacji, które oczekują bogatszych koncepcji początkowych niż pojedynczy ciąg znaków, pokrewne przeciążenia przyjmują bezpośrednio [ImagePlaygroundConcept]. Wiele koncepcji się komponuje: model używa każdej z nich jako ograniczenia lub sygnału. Kolejność ma znaczenie: koncepcje tekstowe ustalają prompt; koncepcje obrazowe ustalają referencję wizualną; koncepcje rysunkowe ustalają zarys.

Warianty ImagePlaygroundConcept

Apple udostępnia kilka konstruktorów ImagePlaygroundConcept⁴:

.text(_:). Krótki opis tekstowy. Najczęstsza koncepcja początkowa.

.image(_:). Obraz źródłowy (zazwyczaj URL albo UIImage/NSImage). Model używa go jako referencji wizualnej dla stylu lub kompozycji.

.drawing(_:). Rysunek, zazwyczaj z PencilKit lub niestandardowej powierzchni do rysowania. Model interpretuje pociągnięcia jako wskazówkę strukturalną.

.extracted(from:title:). Koncepcje wyodrębnione z przeanalizowanego obrazu. Forma dwuargumentowa przyjmuje źródłowy URL (lub typ obrazu) oraz title opisujący wyodrębnienie. Framework wykorzystuje analizę na urządzeniu, aby wyprowadzić z materiału referencyjnego koncepcję nadającą się do generowania.

Koncepcje się komponują: przekazanie [text, image, extracted] do arkusza lub do ImageCreator pozwala modelowi spełnić wiele ograniczeń. Właściwy wzorzec brzmi „wystarczająco konkretny, by dać użyteczny wynik, na tyle luźny, by model miał przestrzeń”: jedna lub dwie konkretne koncepcje plus opcjonalny materiał referencyjny.

ImageCreator: ścieżka programowa

[Aktualizacja: Apple wycofało ImageCreator z dniem 11 czerwca 2026; harmonogram dla iOS 27 oraz sposób migracji opisuje wpis o wycofaniu. Poniższa sekcja pozostaje jako historyczna dokumentacja tego API.]

ImageCreator to programowe API dla aplikacji, które oczekują generowania bez UI³:

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

Metoda images(for:style:limit:) zwraca AsyncSequence wyników ImageCreator.CreatedImage. Asynchroniczny model strumieniowy pozwala aplikacjom prezentować wyniki częściowe (postępujące doprecyzowanie modelu) lub czekać na finalny obraz. Parametr limit: ogranicza liczbę żądanych obrazów; Apple może zwrócić ich mniej w zależności od zasad lub stanu urządzenia.

Ścieżka programowa jest dostępna od iOS 18.4+ i wymaga urządzenia obsługującego Apple Intelligence z włączoną funkcją. Wzorzec sprawdzania dostępności: skonstruować ImageCreator wewnątrz try, a następnie odczytać availableStyles. Pusta kolekcja availableStyles (lub zgłoszony błąd inicjalizatora) sygnalizuje, że generowanie jest niedostępne na bieżącym urządzeniu; aplikacje przechodzą wówczas na ścieżkę niegeneratywną (biblioteka zasobów, obraz przesłany przez użytkownika itp.).

Warianty ImagePlaygroundStyle

Parametr stylu ogranicza estetykę wizualną⁵:

• .animation. Styl postaci animowanych od Apple (zaokrąglone kształty, wyraziste kontury, uproszczone rysy). Przydatny do awatarów, maskotek, przyjaznych ilustracji w UI.
• .illustration. Płaski styl ilustracyjny o estetyce wektorowej. Przydatny do infografik, kart z przepisami, obrazów koncepcyjnych.
• .sketch. Styl szkicu ołówkiem (dodany w późniejszych wydaniach). Przydatny do aplikacji do robienia notatek, prowadzenia dziennika, estetyki odręcznej.

Aplikacje, które chcą zachować spójną estetykę wygenerowanych obrazów (każdy awatar w stylu .animation, każda karta z przepisem w stylu .illustration), blokują styl w swoich wywołaniach generowania; aplikacje, które chcą udostępnić wybór, prezentują selektor stylu mapowany na dostępne przypadki.

Modyfikatory personalizacji i zasad

Dwa modyfikatory SwiftUI pozwalają aplikacjom ograniczać zachowanie Image Playground w ich kontekście⁶:

.imagePlaygroundPersonalizationPolicy(_:). Przyjmuje wartość ImagePlaygroundPersonalizationPolicy: .automatic (domyślna systemowa), .enabled (jawne zezwolenie) lub .disabled (zakaz odwoływania się przez system do treści osobistych, takich jak kontakty czy zdjęcia). Wartości .disabled należy używać w aplikacjach działających w kontekstach wrażliwych na prywatność (medycyna, finanse, komunikacja anonimowa).

.imagePlaygroundGenerationStyle(_:in:). Przyjmuje preferowany styl oraz tablicę dozwolonych stylów. Selektor stylu użytkownika (jeśli jest widoczny) zostaje ograniczony do dozwolonej listy, a preferowany styl jest domyślny. Warto z niego korzystać, gdy estetyka aplikacji wymaga ograniczenia lub zablokowania dostępnych stylów.

Oba modyfikatory respektują konfigurację Apple Intelligence na poziomie systemu jako dolną granicę. Aplikacje nie mogą nadpisać funkcji, które system wyłączył; mogą je jedynie dodatkowo ograniczyć.

Częste błędy

Trzy wzorce z dzienników integracji Image Playground:

Wywołanie ImageCreator() bez przechwycenia błędu inicjalizatora. Na urządzeniach bez Apple Intelligence kreator zgłasza błąd podczas inicjalizacji. Aplikacje, które nie używają try i nie przechwytują błędu, prezentują użytkownikowi mylący komunikat. Rozwiązanie: opakować ImageCreator() w try, sprawdzić availableStyles i zapewnić ścieżkę awaryjną na wypadek niepowodzenia (wyświetlić obraz zastępczy, poprosić użytkownika o włączenie Apple Intelligence w Ustawieniach lub całkowicie ukryć funkcję).

Niedopasowanie ścieżki integracji do zastosowania. Generator awatara profilu, który używa ImageCreator, tworzy jednorazowy awatar, którego użytkownik nie może dostroić; generator jednorazowego awatara, który używa arkusza, dodaje tarcie. Należy dopasować ścieżkę do oczekiwań użytkownika: jeśli chce iterować — arkusz; jeśli chce wynik — ścieżka programowa.

Ignorowanie dolnej granicy zasad systemowych. Aplikacje, które próbują obejść systemowe ustawienia Apple Intelligence (np. generując obrazy w kontekście globalnie wyłączonym przez użytkownika), napotykają błędy zasad. Rozwiązanie: respektować konfigurację systemu; prezentować sensowne błędy, gdy Apple Intelligence jest wyłączone, zamiast cichej awarii.

Co ten wzorzec oznacza dla aplikacji Apple Intelligence

Trzy wnioski.

1. Dobierać ścieżkę integracji według modelu mentalnego użytkownika. Arkusz do twórczej iteracji; ścieżka programowa do jednorazowego generowania w przepływach nieinteraktywnych. Koszt złego wyboru to realne tarcie w UX.

2. Świadomie ograniczać styl i personalizację. Aplikacja do wiadomości, która chce spójnego stylu awatarów, przekazuje pojedynczy dozwolony styl do .imagePlaygroundGenerationStyle(_:in:). Aplikacja do prowadzenia dziennika zorientowana na prywatność ustawia .imagePlaygroundPersonalizationPolicy(.disabled). Wartości domyślne są pobłażliwe (.automatic); świadome ograniczenia sprawiają, że funkcja wydaje się przemyślana.

3. Zawsze sprawdzać availableStyles z ImageCreator() (lub przechwytywać błąd inicjalizatora) i mieć ścieżkę awaryjną. Apple Intelligence wymaga określonego sprzętu (iPhone 15 Pro i nowsze, komputery Mac z procesorami z serii M) oraz zgody użytkownika. Aplikacje, które polegają na Image Playground bez sprawdzania dostępności, zawodzą w mylący sposób na starszych urządzeniach oraz na urządzeniach, gdzie Apple Intelligence jest wyłączone.

Pełny klaster Apple Ecosystem: typowane App Intents; serwery MCP; kwestia routingu; Foundation Models; rozróżnienie między LLM jako środowiskiem uruchomieniowym a narzędziem; trzy powierzchnie; wzorzec jednego źródła prawdy; Dwa serwery MCP; hooki w programowaniu na platformy Apple; Live Activities; środowisko uruchomieniowe watchOS; wnętrzności SwiftUI; przestrzenny model mentalny RealityKit; dyscyplina schematu SwiftData; wzorce Liquid Glass; wieloplatformowe wydawanie; macierz platform; Vision framework; Symbol Effects; inferencja Core ML; Writing Tools API; Swift Testing; Privacy Manifest; dostępność jako platforma; typografia SF Pro; przestrzenne wzorce visionOS; Speech framework; migracje SwiftData; silnik fokusu tvOS; wnętrzności @Observable; protokół Layout w SwiftUI; niestandardowe SF Symbols; AVFoundation HDR; cykl życia treningu watchOS; App Intents 2.0 w iOS 26; o czym odmawiam pisać. Centrum znajduje się w serii Apple Ecosystem. Szerszy kontekst dotyczący iOS z agentami AI opisuje przewodnik po programowaniu agentów na iOS.

FAQ

Czy muszę obsłużyć sytuację, w której Apple Intelligence jest niedostępne?

Tak. Image Playground wymaga urządzenia obsługującego Apple Intelligence (iPhone 15 Pro i nowsze, komputery Mac z procesorami z serii M) z włączoną funkcją. Na nieobsługiwanych urządzeniach arkusz się nie wyświetli, a ImageCreator() zgłosi błąd podczas inicjalizacji. Wzorzec sprawdzania: opakować ImageCreator() w try i sprawdzić availableStyles; pusta kolekcja lub zgłoszony błąd inicjalizatora sygnalizuje, że generowanie jest niedostępne. Należy zapewnić niegeneratywną ścieżkę awaryjną dla użytkowników na nieobsługiwanych urządzeniach.

Czy mogę dostosować UI arkusza?

Nie. Arkusz jest kontrolowany przez system. Aplikacja dostarcza początkową koncepcję i odbiera wynik; wszystko pomiędzy stanowi UI Apple. Jeśli potrzebny jest niestandardowy UI, należy użyć programowego API ImageCreator i zbudować wokół niego własny interfejs iteracji.

Co dzieje się z wygenerowanymi obrazami, gdy użytkownik zamknie arkusz?

Przeciążenie imagePlaygroundSheet z pięcioma parametrami zapewnia oddzielne domknięcia onCompletion i onCancellation. onCompletion wyzwala się z nieopcjonalnym URL, gdy użytkownik wybierze obraz; onCancellation wyzwala się, gdy użytkownik zamknie arkusz bez wyboru. Tymczasowe dane obrazu są usuwane przez system; aplikacje, które chcą zachować obraz, muszą zapisać go we własnym magazynie w procedurze obsługi ukończenia.

Jak Image Playground współgra z uprawnieniami do zdjęć?

Sam arkusz nie wymaga dostępu do biblioteki zdjęć. Jeśli użytkownik odwołuje się do swojej biblioteki zdjęć wewnątrz arkusza (przegląda obraz do wykorzystania jako koncepcja), arkusz wewnętrznie obsługuje prośbę o uprawnienia. Aplikacje nie muszą z góry żądać uprawnień do zdjęć, aby zintegrować się z Image Playground.

Czy mogę generować obrazy w tle?

ImageCreator działa na pierwszym planie; framework zarządza zasobami systemowymi potrzebnymi do generowania. Aplikacje, które chcą generować obrazy w tle, muszą utrzymywać aplikację na pierwszym planie (lub w typie sesji, który zezwala na kontynuowanie wykonywania, jak sesja treningowa opisana w cyklu życia treningu watchOS).

Jak ma się to do LLM z Foundation Models?

Model Image Playground jest oddzielny od LLM-a działającego na urządzeniu z Foundation Models (opisanego w Foundation Models on-device LLM). Oba korzystają ze wspólnej infrastruktury frameworka Apple Intelligence, ale używają różnych wyspecjalizowanych modeli. Aplikacje, które je łączą (prompty wygenerowane przez LLM trafiające do generowania obrazów), komponują oba API w sekwencji.

Bibliografia