Image Playground API: arkusz SwiftUI, programowy Image Creator i kontrola stylu

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

Wpis omawia API na tle dokumentacji Apple. Ramą jest „która ścieżka integracji odpowiada modelowi mentalnemu użytkownika”, ponieważ wybór niewłaściwej ścieżki prowadzi do UX, który 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 prezentujący systemowy arkusz Image Playground. Użytkownik iteruje; aplikacja otrzymuje URL wybranego obrazu poprzez onCompletion (URL nieopcjonalny); anulowanie wywołuje onCancellation².
• ImageCreator().images(for: [ImagePlaygroundConcept], style: ImagePlaygroundStyle, limit: Int) to ścieżka programowa (iOS 18.4+). Metoda zwraca AsyncSequence wyników ImageCreator.CreatedImage³.
• ImagePlaygroundConcept przenosi dane wejściowe używane przez model: opisy tekstowe (.text("a watercolor of a cat")), obrazy źródłowe (.image(...)), rysunki (.drawing(...)) lub koncepcje wyodrębnione z referencji (.extracted(from:title:)).
• ImagePlaygroundStyle wybiera estetykę wizualną. Aplikacje odpytują ImageCreator().availableStyles, aby odkryć, które przypadki obsługuje urządzenie.
• .imagePlaygroundPersonalizationPolicy(_:) przyjmuje .automatic, .enabled lub .disabled. .imagePlaygroundGenerationStyle(_:in:) przyjmuje preferowany styl oraz listę dozwolonych stylów. Należy ich używać w kontekstach wrażliwych na prywatność lub o ustalonej estetyce.

Dwie ścieżki: arkusz a podejście programowe

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

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

• Użytkownik ma kreatywną intencję, której aplikacja nie może w pełni przewidzieć.
• Interakcja jest częścią procesu kreatywnego (aplikacja do wiadomości, aplikacja do notatek, proces personalizacji profilu).
• Użytkownik oczekuje możliwości iteracji przed zatwierdzeniem.

Integracja programowa daje aplikacji bezpośredni dostęp do modelu. Aplikacja dostarcza koncepcje i otrzymuje obrazy bez pokazywania systemowego interfejsu. Należy używać tej ścieżki, gdy:

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

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

Arkusz SwiftUI

imagePlaygroundSheet jest dostarczany w kilku wariantach przeciążeń na View. Kanoniczna forma z 5 parametrami przyjmuje początkową koncepcję, opcjonalną referencję obrazu źródłowego oraz handlery zakoń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 kontrolowany przez system. Użytkownik widzi standardowy interfejs Apple Image Playground (prompty, selektor stylu, siatkę wariantów, przycisk „Done”). Rolą aplikacji jest dostarczenie początkowego promptu i odebranie wyniku. Anulowanie wywołuje dedykowane domknięcie onCancellation, a nie nil URL w zakończeniu; URL przekazany do onCompletion jest nieopcjonalny.

Dla aplikacji, które chcą bogatszych koncepcji początkowych niż pojedynczy ciąg znaków, równoległe przeciążenia akceptują bezpośrednio [ImagePlaygroundConcept]. Wiele koncepcji się komponuje: model używa każdej jako ograniczenia lub sygnału. Kolejność ma znaczenie: koncepcje tekstowe ustanawiają prompt; koncepcje obrazu ustanawiają referencję wizualną; koncepcje rysunku ustanawiają zarys.

Warianty ImagePlaygroundConcept

Apple dostarcza kilka konstruktorów ImagePlaygroundConcept⁴:

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

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

.drawing(_:). Rysunek, zwykle z PencilKit lub niestandardowej powierzchni rysowania. Model interpretuje pociągnięcia jako podpowiedź strukturalną.

.extracted(from:title:). Koncepcje wyodrębnione z analizowanego obrazu. Forma dwuargumentowa przyjmuje źródłowy URL (lub typ obrazu) oraz title opisujący wyodrębnienie. Framework używa analizy na urządzeniu, aby uzyskać z referencji 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 to „wystarczająco konkretne, by wyprodukować użyteczny wynik, wystarczająco luźne, by model miał miejsce”: jedna lub dwie konkretne koncepcje plus opcjonalny materiał referencyjny.

ImageCreator: ścieżka programowa

ImageCreator to programowe API dla aplikacji, które chcą generowania bez interfejsu³:

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ć częściowe wyniki (progresywne udoskonalanie modelu) lub czekać na ostateczny obraz. Parametr limit: ogranicza liczbę żądanych obrazów; Apple może zwrócić mniej w zależności od polityki lub stanu urządzenia.

Ścieżka programowa wymaga iOS 18.4+ oraz urządzenia obsługującego Apple Intelligence z włączoną funkcją. Wzorzec sprawdzania dostępności: skonstruować ImageCreator wewnątrz try, następnie odczytać availableStyles. Pusta kolekcja availableStyles (lub rzucony inicjalizator) sygnalizuje, że generowanie jest niedostępne na bieżącym urządzeniu; aplikacje przechodzą wówczas na ścieżkę niegenerującą (biblioteka zasobów, obraz wgrany przez użytkownika itp.).

Warianty ImagePlaygroundStyle

Parametr stylu ogranicza estetykę wizualną⁵:

• .animation. Styl animowanej postaci od Apple (zaokrąglone formy, wyraźne kontury, uproszczone rysy). Przydatny dla awatarów, maskotek, przyjaznych ilustracji UI.
• .illustration. Płaski styl ilustracyjny o estetyce wektorowej. Przydatny dla infografik, kart przepisów, obrazowania koncepcyjnego.
• .sketch. Styl szkicu ołówkiem (dodany w późniejszych wydaniach). Przydatny dla aplikacji do notatek, dziennika, estetyki ręcznie rysowanej.

Aplikacje, które chcą spójnej estetyki w generowanych obrazach (każdy awatar w stylu .animation, każda karta przepisu w stylu .illustration), blokują styl w wywołaniach generowania; aplikacje, które chcą udostępnić wybór, prezentują selektor stylu mapowany na dostępne przypadki.

Modyfikatory personalizacji i polityki

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

.imagePlaygroundPersonalizationPolicy(_:). Przyjmuje wartość ImagePlaygroundPersonalizationPolicy: .automatic (domyślne ustawienie systemowe), .enabled (jawne zezwolenie) lub .disabled (zakaz odwoływania się systemu do osobistych treści, takich jak kontakty czy zdjęcia). Należy używać .disabled w aplikacjach w kontekstach wrażliwych na prywatność (medyczne, finansowe, anonimowa komunikacja).

.imagePlaygroundGenerationStyle(_:in:). Przyjmuje preferowany styl oraz tablicę dozwolonych stylów. Selektor stylu użytkownika (jeśli widoczny) jest ograniczony do dozwolonej listy, a preferowany styl jest domyślny. Należy go używać, 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ą nadpisywać funkcji wyłączonych przez system; mogą jedynie nakładać dalsze ograniczenia.

Częste błędy

Trzy wzorce z logów integracji Image Playground:

Wywoływanie ImageCreator() bez przechwycenia błędu inicjalizatora. Na urządzeniach bez Apple Intelligence kreator rzuca błąd przy 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ę zapasową w przypadku awarii (wyświetlić zastępnik, zaproponować użytkownikowi włączenie Apple Intelligence w Ustawieniach lub całkowicie ukryć funkcję).

Niedopasowanie ścieżki integracji do przypadku użycia. Generator awatara profilowego używający ImageCreator produkuje jednorazowy awatar, którego użytkownik nie może dostroić; jednorazowy generator awatara używający arkusza dodaje tarcie. Należy dopasować ścieżkę do oczekiwań użytkownika: jeśli chce iterować — arkusz; jeśli chce wynik — programowo.

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

Co ten wzorzec oznacza dla aplikacji Apple Intelligence

Trzy wnioski.

1. Należy wybierać ścieżkę integracji według modelu mentalnego użytkownika. Arkusz dla iteracji kreatywnej; programowo dla jednorazowego generowania w przepływach nieinteraktywnych. Koszt złego wyboru to realne tarcie UX.

2. Należy świadomie ograniczać styl i personalizację. Aplikacja do wiadomości pragnąca spójnego stylu awatara przekazuje pojedynczy dozwolony styl do .imagePlaygroundGenerationStyle(_:in:). Aplikacja dziennikowa skupiona na prywatności ustawia .imagePlaygroundPersonalizationPolicy(.disabled). Wartości domyślne są permisywne (.automatic); świadome ograniczenia sprawiają, że funkcja wydaje się zamierzona.

3. Należy zawsze sprawdzać availableStyles w ImageCreator() (lub przechwytywać błąd inicjalizatora) i mieć ścieżkę zapasową. Apple Intelligence wymaga konkretnego sprzętu (iPhone 15 Pro i nowszy, komputery Mac z serii M) oraz zgody użytkownika. Aplikacje zależne od Image Playground bez kontroli dostępności zawodzą w mylący sposób na starszych urządzeniach oraz na urządzeniach z wyłączonym Apple Intelligence.

Pełny klaster Apple Ecosystem: typowane App Intents; serwery MCP; pytanie o routing; Foundation Models; rozróżnienie LLM runtime vs tooling; trzy powierzchnie; wzorzec pojedynczego źródła prawdy; Dwa serwery MCP; hooki dla rozwoju Apple; Live Activities; runtime watchOS; wnętrzności SwiftUI; model mentalny przestrzeni RealityKit; dyscyplina schematu SwiftData; wzorce Liquid Glass; wysyłka wieloplatformowa; matryca platform; framework Vision; Symbol Effects; wnioskowanie Core ML; Writing Tools API; Swift Testing; Privacy Manifest; Dostępność jako platforma; typografia SF Pro; wzorce przestrzenne visionOS; framework Speech; migracje SwiftData; silnik fokusu tvOS; wnętrzności @Observable; protokół Layout SwiftUI; niestandardowe SF Symbols; HDR w AVFoundation; cykl życia treningu watchOS; App Intents 2.0 w iOS 26; o czym odmawiam pisania. Hub znajduje się w Apple Ecosystem Series. Szerszy kontekst iOS z agentami AI znajduje się w przewodniku iOS Agent Development.

FAQ

Czy muszę obsługiwać sytuację, gdy Apple Intelligence jest niedostępne?

Tak. Image Playground wymaga urządzenia obsługującego Apple Intelligence (iPhone 15 Pro i nowszy, komputery Mac z serii M) z włączoną funkcją. Na nieobsługiwanych urządzeniach arkusz nie zostanie wyświetlony, a ImageCreator() rzuci błąd przy inicjalizacji. Wzorzec sprawdzania: opakować ImageCreator() w try i sprawdzić availableStyles; pusta kolekcja lub rzucony inicjalizator sygnalizują, że generowanie jest niedostępne. Należy zapewnić niegenerującą ścieżkę zapasową dla nieobsługiwanych użytkowników.

Czy mogę dostosować interfejs arkusza?

Nie. Arkusz jest kontrolowany przez system. Aplikacja dostarcza początkową koncepcję i otrzymuje wynik; wszystko pomiędzy to interfejs Apple. Jeśli potrzebny jest niestandardowy interfejs, 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?

Pięcioparametrowe przeciążenie imagePlaygroundSheet zapewnia oddzielne domknięcia onCompletion i onCancellation. onCompletion uruchamia się z nieopcjonalnym URL, gdy użytkownik wybierze obraz; onCancellation uruchamia się, gdy użytkownik zamknie arkusz bez dokonania wyboru. Tymczasowe dane obrazu są czyszczone przez system; aplikacje, które chcą zachować obraz, muszą zapisać go we własnej pamięci w handlerze zakończenia.

Jak Image Playground współdziała 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ądając obraz do użycia jako koncepcji), arkusz obsługuje monit o uprawnienia wewnętrznie. Aplikacje nie muszą żądać uprawnień do zdjęć z wyprzedzeniem dla integracji Image Playground.

Czy mogę generować obrazy w tle?

ImageCreator działa na pierwszym planie; framework zarządza zasobami systemowymi dla generowania. Aplikacje, które chcą generowania obrazów w tle, muszą utrzymywać aplikację na pierwszym planie (lub w typie sesji pozwalającym na kontynuowanie wykonywania, takim jak sesja treningowa omówiona w cyklu życia treningu watchOS).

Jak to się ma do LLM Foundation Models?

Model Image Playground jest oddzielony od LLM Foundation Models na urządzeniu (omówionego w Foundation Models LLM na urządzeniu). Oba dzielą infrastrukturę frameworka Apple Intelligence, ale używają różnych wyspecjalizowanych modeli. Aplikacje, które je łączą (prompty wygenerowane przez LLM zasilające generowanie obrazów), komponują oba API sekwencyjnie.

Bibliografia