Image Playground API: SwiftUI Sheet, 프로그래밍 방식 Image Creator, 그리고 스타일 제어

Apple Intelligence의 Image Playground는 앱에 두 가지 통합 경로를 노출합니다. SwiftUI imagePlaygroundSheet() 모디파이어는 시스템의 사용자 대면 이미지 생성 UI를 표시합니다. 개발자는 시작 컨셉(텍스트 또는 이미지)을 전달하고, 사용자는 시트 내부에서 반복 작업을 수행하며, 결과는 앱으로 반환됩니다. ImageCreator API는 동일한 생성 파이프라인을 프로그래밍 방식으로 실행합니다. 개발자는 ImagePlaygroundConcept 객체 배열과 스타일을 제공하고, 프레임워크는 UI를 표시하지 않은 채 생성된 이미지를 반환합니다¹. 두 경로는 서로 다른 사용 사례를 대상으로 합니다. 사용자가 반복 작업을 해야 할 때는 시트 통합이 적합하고, 앱이 특정 생성 요청을 가지고 있으며 결과를 직접 표시할 때는 프로그래밍 방식 통합이 적합합니다.

이 글은 Apple의 문서를 바탕으로 API를 살펴봅니다. 프레임은 “어떤 통합 경로가 사용자의 멘탈 모델과 일치하는가”입니다. 잘못된 경로를 선택하면 사용자에게서 너무 많은 제어권을 빼앗거나(사용자가 반복 작업을 원했는데 프로그래밍 방식을 사용한 경우) 너무 적게 주는(원샷 결과를 기대했는데 시트를 사용한 경우) UX가 만들어지기 때문입니다.

TL;DR

• imagePlaygroundSheet(isPresented:concept:sourceImage:onCompletion:onCancellation:)은 시스템 Image Playground 시트를 표시하는 SwiftUI 모디파이어입니다. 사용자가 반복 작업을 수행하고, 앱은 onCompletion을 통해 선택된 이미지의 URL을 받습니다(옵셔널이 아닌 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:)는 선호 스타일과 허용 스타일 목록을 받습니다. 프라이버시에 민감하거나 미학이 고정된 컨텍스트에서 이 모디파이어를 사용하세요.

두 가지 경로: 시트 vs 프로그래밍 방식

두 통합 경로 사이의 결정은 누가 반복 작업을 제어하느냐에 관한 것입니다.

시트 통합은 사용자에게 시스템의 전체 이미지 생성 UI를 넘깁니다. 사용자는 프롬프트를 입력하고, 변형을 선택하며, 최종 이미지를 고릅니다. 앱의 역할은 시작 컨셉으로 시트를 실행하고 선택된 결과를 받는 것입니다. 다음과 같은 경우에 사용하세요.

• 앱이 완전히 예측할 수 없는 창의적 의도를 사용자가 가지고 있을 때.
• 상호작용이 창의적 워크플로의 일부일 때(메시징 앱, 노트 앱, 프로필 커스터마이징 흐름).
• 사용자가 확정하기 전에 반복 작업을 기대할 때.

프로그래밍 방식 통합은 앱에 모델을 직접 제공합니다. 앱은 컨셉을 제공하고 시스템 UI를 표시하지 않은 채 이미지를 받습니다. 다음과 같은 경우에 사용하세요.

• 생성이 비대화형 흐름의 일부일 때(시스템 생성 아바타, 레시피 카드를 위한 결정론적 에셋, 원샷 일러스트).
• 앱이 특정 미학적 요구사항을 가지고 있을 때(항상 일러스트 스타일, 항상 한 장의 이미지).
• 사용자가 반복 과정을 봐서는 안 되며, 결과만이 그들이 신경 쓰는 것일 때.

두 경로는 동일한 기본 모델을 공유하며, 동일한 사용자 수준 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:). 분석된 이미지에서 추출된 컨셉입니다. 두 인자 형태는 소스 URL(또는 이미지 타입)과 추출을 설명하는 title을 받습니다. 프레임워크는 온디바이스 분석을 사용하여 참조에서 생성에 적합한 컨셉을 도출합니다.

컨셉은 조합됩니다. [text, image, extracted]을 시트나 ImageCreator에 전달하면 모델이 여러 제약 조건을 충족할 수 있습니다. 올바른 패턴은 “유용한 출력을 만들 만큼 구체적이면서, 모델이 여지를 가질 만큼 느슨한” 것입니다. 한두 개의 구체적인 컨셉과 옵셔널 참조 이미지의 조합이 좋습니다.

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 스타일)은 생성 호출에서 스타일을 고정합니다. 선택권을 노출하고 싶은 앱은 사용 가능한 케이스에 매핑되는 스타일 선택기를 표시합니다.

개인화 및 정책 모디파이어

두 SwiftUI 모디파이어를 통해 앱은 자신의 컨텍스트에서 Image Playground 동작을 제약할 수 있습니다⁶.

.imagePlaygroundPersonalizationPolicy(_:). ImagePlaygroundPersonalizationPolicy 값을 받습니다. .automatic(시스템 기본값), .enabled(명시적으로 허용), 또는 .disabled(시스템이 연락처/사진 같은 개인 콘텐츠를 참조하는 것을 금지)입니다. 프라이버시에 민감한 컨텍스트(의료, 금융, 익명 통신)에서는 .disabled를 사용하세요.

.imagePlaygroundGenerationStyle(_:in:). 선호 스타일과 허용된 스타일 배열을 받습니다. 사용자의 스타일 선택기(보이는 경우)는 허용 목록으로 제한되며, 선호 스타일이 기본값이 됩니다. 앱의 미학이 사용 가능한 스타일을 제약하거나 잠가야 할 때 사용하세요.

두 모디파이어 모두 시스템 수준 Apple Intelligence 설정을 하한선으로 존중합니다. 앱은 시스템이 비활성화한 기능을 재정의할 수 없습니다. 더 제약할 수만 있습니다.

일반적인 실패

Image Playground 통합 로그에서 나타나는 세 가지 패턴입니다.

이니셜라이저 오류를 잡지 않고 ImageCreator()를 호출하기. Apple Intelligence를 지원하지 않는 디바이스에서는 생성자가 초기화 시 오류를 던집니다. try와 catch를 사용하지 않는 앱은 사용자에게 혼란스러운 오류를 노출합니다. 해결 방법은 ImageCreator()를 try로 감싸고, availableStyles를 검사하며, 실패 시 폴백 경로를 제공하는 것입니다(플레이스홀더 표시, 사용자에게 설정에서 Apple Intelligence를 활성화하도록 유도, 또는 기능을 완전히 숨김).

통합 경로를 사용 사례에 맞지 않게 매칭하기. ImageCreator를 사용하는 프로필 아바타 생성기는 사용자가 조정할 수 없는 원샷 아바타를 만듭니다. 시트를 사용하는 원샷 아바타 생성기는 마찰을 추가합니다. 경로를 사용자의 기대에 맞추세요. 반복 작업을 원한다면 시트, 결과를 원한다면 프로그래밍 방식입니다.

시스템의 정책 하한선을 무시하기. 시스템 Apple Intelligence 설정을 우회하려는 앱(예: 사용자가 전역적으로 비활성화한 컨텍스트에서 이미지를 생성)은 정책 오류에 부딪힙니다. 해결 방법은 시스템 설정을 존중하는 것입니다. Apple Intelligence가 비활성화되었을 때 무성 실패 대신 의미 있는 오류를 표시하세요.

이 패턴이 Apple Intelligence 앱에 의미하는 것

세 가지 시사점입니다.

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 구분; 세 가지 표면; 단일 진실 공급원 패턴; 두 개의 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에 있습니다. iOS와 AI 에이전트의 더 폭넓은 컨텍스트는 iOS Agent Development guide를 참조하세요.

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 생성 프롬프트가 이미지 생성에 공급됨)은 두 API를 순차적으로 조합합니다.

참고 자료