← 모든 글

Image Playground API: SwiftUI 시트, 프로그래밍 방식 이미지 생성, 그리고 스타일 제어

7분 소요

업데이트 (2026년 6월 11일): Apple은 이 글에서 다루는 프로그래밍 방식 경로인 ImageCreator를 중단합니다. iOS 27, iPadOS 27, macOS 27, visionOS 27에서 동작이 멈춥니다. 이 글의 나머지 부분에서 다루는 시트 기반 API는 계속 지원되는 경로로 남습니다. 일정과 마이그레이션은 전체 지원 중단 글에서 읽어 보세요.

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

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

TL;DR

  • imagePlaygroundSheet(isPresented:concept:sourceImage:onCompletion:onCancellation:)는 시스템 Image Playground 시트를 표시하는 SwiftUI 모디파이어입니다. 사용자가 반복 작업을 거치고, 앱은 onCompletion을 통해 선택된 이미지의 URL(옵셔널이 아닌 URL)을 받습니다. 취소 시에는 onCancellation이 호출됩니다2.
  • ImageCreator().images(for: [ImagePlaygroundConcept], style: ImagePlaygroundStyle, limit: Int)는 프로그래밍 방식 경로입니다(iOS 18.4+). 이 메서드는 ImageCreator.CreatedImage 결과의 AsyncSequence를 반환합니다3.
  • 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개 매개변수 형식은 시작 개념, 선택적 소스 이미지 참조, 그리고 완료 및 취소 핸들러를 받습니다2.

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 인터페이스(프롬프트, 스타일 선택기, 변형 그리드, “완료” 버튼)를 봅니다. 앱의 역할은 시작 프롬프트를 제공하고 결과를 받는 것입니다. 취소는 완료 시 nil URL이 아니라 전용 onCancellation 클로저를 호출합니다. onCompletion에 전달되는 URL은 옵셔널이 아닙니다.

문자열 하나보다 더 풍부한 시작 개념을 원하는 앱을 위해, 형제 오버로드는 [ImagePlaygroundConcept]를 직접 받습니다. 여러 개념이 조합됩니다. 모델은 각 개념을 제약 조건이나 신호로 사용합니다. 순서가 중요합니다. 텍스트 개념은 프롬프트를 정하고, 이미지 개념은 시각적 참조를 정하며, 그림 개념은 윤곽을 정합니다.

ImagePlaygroundConcept 변형

Apple은 여러 ImagePlaygroundConcept 생성자를 제공합니다4.

.text(_:). 짧은 텍스트 설명입니다. 가장 흔히 쓰이는 시작 개념입니다.

.image(_:). 소스 이미지입니다(일반적으로 URL 또는 UIImage/NSImage). 모델은 이를 스타일이나 구성을 위한 시각적 참조로 사용합니다.

.drawing(_:). 그림으로, 일반적으로 PencilKit이나 커스텀 드로잉 표면에서 가져옵니다. 모델은 그 획을 구조적 힌트로 해석합니다.

.extracted(from:title:). 분석된 이미지에서 추출한 개념입니다. 두 인자 형식은 소스 URL(또는 이미지 타입)과 추출을 설명하는 title을 받습니다. 프레임워크는 온디바이스 분석을 사용해 참조로부터 생성에 적합한 개념을 도출합니다.

개념은 조합됩니다. [text, image, extracted]를 시트나 ImageCreator에 전달하면 모델이 여러 제약 조건을 충족할 수 있습니다. 올바른 패턴은 “유용한 출력을 만들 만큼 구체적이되, 모델에 여지가 있을 만큼 느슨하게”입니다. 즉, 하나나 두 개의 구체적 개념에 선택적 참조 이미지를 더하는 것입니다.

ImageCreator: 프로그래밍 방식 경로

[업데이트: Apple은 2026년 6월 11일자로 ImageCreator를 중단했습니다. iOS 27 일정과 마이그레이션 방법은 지원 중단 글을 참고하세요. 아래 섹션은 이 API의 역사적 문서로 남겨 둡니다.]

ImageCreator는 UI 없이 생성을 원하는 앱을 위한 프로그래밍 방식 API입니다3.

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 변형

스타일 매개변수는 시각적 미감을 제약합니다5.

  • .animation. Apple의 애니메이션 캐릭터 스타일입니다(둥근 형태, 굵은 윤곽선, 단순화된 이목구비). 아바타, 마스코트, 친근한 UI 일러스트레이션에 유용합니다.
  • .illustration. 벡터 같은 미감을 지닌 평면 일러스트레이션 스타일입니다. 인포그래픽, 레시피 카드, 개념적 이미지에 유용합니다.
  • .sketch. 연필 스케치 스타일입니다(이후 릴리스에서 추가됨). 메모 앱, 저널링, 손으로 그린 듯한 미감에 유용합니다.

생성된 이미지 전반에 일관된 미감을 원하는 앱(모든 아바타를 .animation 스타일로, 모든 레시피 카드를 .illustration 스타일로)은 생성 호출에서 스타일을 고정합니다. 선택권을 노출하고 싶은 앱은 사용 가능한 케이스에 매핑되는 스타일 선택기를 보여 줍니다.

개인화 및 정책 모디파이어

두 SwiftUI 모디파이어를 통해 앱은 자신의 맥락에서 Image Playground 동작을 제약할 수 있습니다6.

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

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

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

흔한 실패

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

이니셜라이저 오류를 잡지 않고 ImageCreator()를 호출하기. Apple Intelligence가 없는 기기에서는 생성자가 초기화 시 예외를 던집니다. try로 잡지 않는 앱은 사용자에게 혼란스러운 오류를 노출합니다. 해결책: 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 시리즈에 있습니다. iOS와 AI 에이전트에 관한 더 넓은 맥락은 iOS 에이전트 개발 가이드를 참고하세요.

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를 순차적으로 조합합니다.

References

  1. Apple Developer Documentation: Image Playground. The framework reference covering the SwiftUI sheet integration plus the programmatic ImageCreator API. ↩

  2. Apple Developer Documentation: imagePlaygroundSheet(isPresented:concept:onCompletion:). The SwiftUI view modifier that presents the system Image Playground UI. ↩↩

  3. Apple Developer Documentation: ImageCreator. The programmatic API (iOS 18.4+) with the images(for:style:limit:) method returning an async stream of generated results. ↩↩

  4. Apple Developer Documentation: ImagePlaygroundConcept. The concept variants (.text, .image, .drawing, .extracted) that compose into generation requests. ↩

  5. Apple Developer Documentation: ImagePlaygroundStyle. The available style cases (.animation, .illustration, .sketch) for visual aesthetic control. ↩

  6. Apple Developer Documentation: imagePlaygroundPersonalizationPolicy(_:) and imagePlaygroundGenerationStyle(_:). The view modifiers for constraining personalization and locking the generation style. ↩

관련 게시물

Genmoji와 NSAdaptiveImageGlyph: iOS 18+에서의 인라인 이모지

Genmoji는 속성 텍스트에서 NSAdaptiveImageGlyph로 제공됩니다. TextKit 2를 사용하는 UITextView 앱은 supportsAdaptiveImageGlyph를 활성화하고 직렬화를 처리합니…

6 분 소요

Apple의 Translation 프레임워크: 무료, 온디바이스, 그리고 생각보다 날카롭다

Apple의 Translation 프레임워크: translationPresentation과 TranslationSession을 통한 무료 온디바이스 번역, 그리고 데모가 건너뛰는 오프라인 다운로드의 까다로운 지점들.

7 분 소요

Loop Engineering: Loops Win Where Verification Is Cheap

Loop engineering, checked against Boris Cherny's full transcripts: every loop he names has cheap verification. That cons…

19 분 소요