Image Playground API: SwiftUI Sheet, Image Creator Programático e Controle de Estilo

O Image Playground da Apple Intelligence expõe dois caminhos de integração para apps. O modificador SwiftUI imagePlaygroundSheet() apresenta a UI de geração de imagens voltada ao usuário do sistema; o desenvolvedor passa um conceito inicial (texto ou imagem), o usuário itera dentro da sheet, e o resultado retorna ao app. O API ImageCreator executa o mesmo pipeline de geração de forma programática: o desenvolvedor fornece um array de objetos ImagePlaygroundConcept mais um estilo, e o framework retorna as imagens geradas sem expor uma UI¹. Os dois caminhos miram em casos de uso diferentes. A integração via sheet é a escolha certa quando o usuário deve iterar; a integração programática é a escolha certa quando o app tem uma solicitação de geração específica e exibe o resultado diretamente.

O post percorre o API confrontando-o com a documentação da Apple. O recorte é “qual caminho de integração combina com o modelo mental do usuário”, porque escolher o caminho errado produz uma UX que tira controle demais do usuário (programático quando o usuário queria iterar) ou de menos (sheet quando o usuário esperava um resultado único).

TL;DR

• imagePlaygroundSheet(isPresented:concept:sourceImage:onCompletion:onCancellation:) é o modificador SwiftUI que apresenta a sheet do Image Playground do sistema. O usuário itera; o app recebe a URL da imagem escolhida via onCompletion (URL não opcional); o cancelamento dispara onCancellation².
• ImageCreator().images(for: [ImagePlaygroundConcept], style: ImagePlaygroundStyle, limit: Int) é o caminho programático (iOS 18.4+). O método retorna um AsyncSequence de resultados ImageCreator.CreatedImage³.
• ImagePlaygroundConcept carrega a entrada que o modelo usa: descrições textuais (.text("a watercolor of a cat")), imagens-fonte (.image(...)), desenhos (.drawing(...)) ou conceitos extraídos de uma referência (.extracted(from:title:)).
• ImagePlaygroundStyle escolhe a estética visual. Os apps consultam ImageCreator().availableStyles para descobrir quais casos o dispositivo suporta.
• .imagePlaygroundPersonalizationPolicy(_:) aceita .automatic, .enabled ou .disabled. .imagePlaygroundGenerationStyle(_:in:) recebe um estilo preferido e uma lista de estilos permitidos. Use isso para contextos sensíveis à privacidade ou com estética travada.

Os dois caminhos: sheet vs programático

A decisão entre os dois caminhos de integração é sobre quem controla a iteração.

Integração via sheet entrega ao usuário a UI completa de geração de imagens do sistema. O usuário digita prompts, escolhe variações e seleciona a imagem final. O trabalho do app é abrir a sheet com um conceito inicial e receber o resultado escolhido. Use isso quando:

• O usuário tem uma intenção criativa que o app não consegue prever totalmente.
• A interação faz parte de um fluxo criativo (um app de mensagens, um app de notas, um fluxo de personalização de perfil).
• O usuário espera iterar antes de confirmar.

Integração programática entrega o modelo diretamente ao app. O app fornece os conceitos e recebe imagens de volta, sem mostrar a UI do sistema. Use isso quando:

• A geração faz parte de um fluxo não interativo (um avatar gerado pelo sistema, um asset determinístico para um cartão de receita, uma ilustração de uso único).
• O app tem um requisito estético específico (sempre estilo ilustração, sempre uma imagem).
• O usuário não deve ver a iteração; o que importa para ele é o resultado.

Os dois caminhos compartilham o modelo subjacente e respeitam a mesma configuração de Apple Intelligence em nível de usuário. A escolha é puramente de UX.

A SwiftUI Sheet

imagePlaygroundSheet vem em diversas variantes sobrecarregadas em View. A forma canônica de 5 parâmetros recebe um conceito inicial, uma referência opcional de imagem-fonte, mais handlers de conclusão e cancelamento²:

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

A UX da sheet é controlada pelo sistema. O usuário vê a interface padrão do Image Playground da Apple (prompts, seletor de estilo, grid de variações, botão “Done”). O papel do app é fornecer o prompt inicial e receber o resultado. O cancelamento dispara a closure dedicada onCancellation em vez de uma URL nula em onCompletion; a URL passada para onCompletion é não opcional.

Para apps que querem conceitos iniciais mais ricos do que uma única string, sobrecargas irmãs aceitam [ImagePlaygroundConcept] diretamente. Vários conceitos compõem: o modelo usa cada um como restrição ou sinal. A ordem importa: conceitos de texto estabelecem o prompt; conceitos de imagem estabelecem uma referência visual; conceitos de desenho estabelecem um contorno.

Variantes de ImagePlaygroundConcept

A Apple oferece vários construtores de ImagePlaygroundConcept⁴:

.text(_:). Uma descrição textual curta. O conceito inicial mais comum.

.image(_:). Uma imagem-fonte (tipicamente uma URL ou UIImage/NSImage). O modelo a usa como referência visual de estilo ou composição.

.drawing(_:). Um desenho, tipicamente do PencilKit ou de uma superfície de desenho personalizada. O modelo interpreta os traços como uma dica estrutural.

.extracted(from:title:). Conceitos extraídos de uma imagem analisada. A forma de dois argumentos recebe uma URL de fonte (ou tipo de imagem) e um title descrevendo a extração. O framework usa análise no dispositivo para derivar um conceito apropriado para geração a partir da referência.

Conceitos compõem: passar [text, image, extracted] para a sheet ou para o ImageCreator permite que o modelo satisfaça várias restrições. O padrão correto é “específico o suficiente para produzir uma saída útil, frouxo o suficiente para o modelo ter espaço”: um ou dois conceitos concretos mais imagens de referência opcionais.

ImageCreator: O caminho programático

ImageCreator é o API programático para apps que querem geração sem 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)")
}

O método images(for:style:limit:) retorna um AsyncSequence de resultados ImageCreator.CreatedImage. O modelo de streaming assíncrono permite aos apps exibir resultados parciais (o refinamento progressivo do modelo) ou aguardar a imagem final. O parâmetro limit: limita o número de imagens solicitadas; a Apple pode retornar menos com base em política ou estado do dispositivo.

O caminho programático é iOS 18.4+ e exige um dispositivo compatível com Apple Intelligence com o recurso ativado. O padrão de verificação de disponibilidade: construa ImageCreator dentro de try e depois leia availableStyles. Uma coleção availableStyles vazia (ou um inicializador que lança) sinaliza que a geração não está disponível no dispositivo atual; os apps recorrem a um caminho não generativo (biblioteca de assets, imagem enviada pelo usuário, etc.).

Variantes de ImagePlaygroundStyle

O parâmetro de estilo restringe a estética visual⁵:

• .animation. O estilo de personagem animado da Apple (formas arredondadas, contornos marcantes, traços simplificados). Útil para avatares, mascotes, ilustrações de UI amigáveis.
• .illustration. Estilo ilustrado plano com estética de aparência vetorial. Útil para infográficos, cartões de receita, imagens conceituais.
• .sketch. Estilo de esboço a lápis (adicionado em versões posteriores). Útil para apps de anotações, journaling, estéticas desenhadas à mão.

Apps que querem uma estética consistente entre as imagens geradas (todo avatar no estilo .animation, todo cartão de receita no estilo .illustration) travam o estilo nas chamadas de geração; apps que querem expor a escolha apresentam um seletor de estilo que mapeia para os casos disponíveis.

Modificadores de personalização e política

Dois modificadores SwiftUI permitem aos apps restringir o comportamento do Image Playground em seu contexto⁶:

.imagePlaygroundPersonalizationPolicy(_:). Recebe um valor ImagePlaygroundPersonalizationPolicy: .automatic (padrão do sistema), .enabled (permitir explicitamente) ou .disabled (proibir o sistema de referenciar conteúdo pessoal como contatos/fotos). Use .disabled para apps em contextos sensíveis à privacidade (médico, financeiro, comunicação anônima).

.imagePlaygroundGenerationStyle(_:in:). Recebe um estilo preferido e um array de estilos permitidos. O seletor de estilo do usuário (se visível) fica restrito à lista permitida, e o estilo preferido é o padrão. Use isso quando a estética do app exige restringir ou travar os estilos disponíveis.

Ambos os modificadores respeitam a configuração de Apple Intelligence em nível de sistema como piso. Os apps não podem sobrepor recursos que o sistema desativou; só podem restringir mais.

Falhas comuns

Três padrões dos logs de integração com o Image Playground:

Chamar ImageCreator() sem capturar o erro do inicializador. Em dispositivos sem Apple Intelligence, o creator lança erro na inicialização. Apps que não usam try e captura expõem um erro confuso ao usuário. Correção: envolver ImageCreator() em try, inspecionar availableStyles e fornecer um caminho de fallback em caso de falha (exibir um placeholder, pedir ao usuário para ativar a Apple Intelligence em Settings ou ocultar o recurso por completo).

Descasamento entre o caminho de integração e o caso de uso. Um gerador de avatar de perfil que usa ImageCreator produz um avatar único que o usuário não consegue ajustar; um gerador de avatar único que usa a sheet adiciona atrito. Combine o caminho com a expectativa do usuário: se ele quer iterar, sheet; se ele quer um resultado, programático.

Ignorar o piso de política do sistema. Apps que tentam burlar as configurações de Apple Intelligence do sistema (por exemplo, gerando imagens em um contexto que o usuário desativou globalmente) batem em erros de política. Correção: respeite a configuração do sistema; exponha erros significativos quando a Apple Intelligence está desativada, em vez de uma falha silenciosa.

O que esse padrão significa para apps de Apple Intelligence

Três conclusões.

1. Escolha o caminho de integração pelo modelo mental do usuário. Sheet para iteração criativa; programático para geração única em fluxos não interativos. O custo de escolher errado é atrito real de UX.

2. Restrinja estilo e personalização de forma deliberada. Um app de mensagens que quer estilo de avatar consistente passa um único estilo permitido para .imagePlaygroundGenerationStyle(_:in:). Um app de journaling focado em privacidade define .imagePlaygroundPersonalizationPolicy(.disabled). Os padrões são permissivos (.automatic); restrições deliberadas fazem o recurso parecer intencional.

3. Sempre verifique availableStyles de ImageCreator() (ou capture o erro do inicializador) e tenha um fallback. A Apple Intelligence exige hardware específico (iPhone 15 Pro e mais recentes, Macs com chips da série M) mais opt-in do usuário. Apps que dependem do Image Playground sem verificações de disponibilidade falham de forma confusa em dispositivos mais antigos e em dispositivos onde a Apple Intelligence está desativada.

O cluster completo do Apple Ecosystem: App Intents tipados; servidores MCP; a questão de roteamento; Foundation Models; a distinção entre LLM de runtime vs ferramental; três superfícies; o padrão de fonte única da verdade; Dois servidores MCP; hooks para desenvolvimento Apple; Live Activities; o contrato de runtime do watchOS; internals do SwiftUI; o modelo mental espacial do RealityKit; disciplina de schema do SwiftData; padrões do Liquid Glass; shipping multiplataforma; a matriz de plataformas; o framework Vision; Symbol Effects; inferência com Core ML; API das Writing Tools; Swift Testing; Privacy Manifest; acessibilidade como plataforma; tipografia SF Pro; padrões espaciais do visionOS; framework Speech; migrações no SwiftData; focus engine do tvOS; internals do @Observable; protocolo Layout do SwiftUI; SF Symbols personalizados; HDR no AVFoundation; ciclo de vida de workout no watchOS; App Intents 2.0 no iOS 26; sobre o que me recuso a escrever. O hub está na Série Apple Ecosystem. Para um contexto mais amplo de iOS com agentes de IA, veja o guia de iOS Agent Development.

FAQ

Preciso lidar com a Apple Intelligence não estando disponível?

Sim. O Image Playground exige um dispositivo compatível com Apple Intelligence (iPhone 15 Pro e mais recentes, Macs com chips da série M) com o recurso ativado. Em dispositivos não suportados, a sheet não será apresentada e ImageCreator() lançará erro na inicialização. O padrão de verificação: envolver ImageCreator() em try e inspecionar availableStyles; uma coleção vazia ou um inicializador que lança sinaliza que a geração não está disponível. Forneça um fallback não generativo para usuários não suportados.

Posso personalizar a UI da sheet?

Não. A sheet é controlada pelo sistema. O app fornece o conceito inicial e recebe o resultado; tudo que está entre os dois é UI da Apple. Se você precisa de uma UI personalizada, use o API programático ImageCreator e construa sua própria interface de iteração ao redor dele.

O que acontece com as imagens geradas quando o usuário fecha a sheet?

A sobrecarga de 5 parâmetros do imagePlaygroundSheet fornece closures separadas onCompletion e onCancellation. onCompletion dispara com uma URL não opcional quando o usuário escolhe uma imagem; onCancellation dispara quando o usuário fecha sem escolher. Os dados temporários da imagem são limpos pelo sistema; apps que querem manter uma imagem precisam salvá-la em seu próprio armazenamento dentro do handler de conclusão.

Como o Image Playground interage com permissões de fotos?

A sheet por si só não exige acesso à biblioteca de fotos. Se o usuário referenciar sua biblioteca de fotos dentro da sheet (navegando por uma imagem para usar como conceito), a sheet trata a solicitação de permissão internamente. Os apps não precisam solicitar permissão de fotos antecipadamente para a integração com o Image Playground.

Posso gerar imagens em segundo plano?

ImageCreator roda em primeiro plano; o framework gerencia os recursos do sistema para a geração. Apps que querem geração de imagens em segundo plano precisam manter o app em primeiro plano (ou em um tipo de sessão que permita execução continuada, como uma sessão de workout coberta em ciclo de vida de workout no watchOS).

Como isso se relaciona com o LLM Foundation Models?

O modelo do Image Playground é separado do LLM Foundation Models no dispositivo (coberto em LLM Foundation Models no dispositivo). Os dois compartilham a infraestrutura do framework Apple Intelligence, mas usam modelos especializados diferentes. Apps que combinam os dois (prompts gerados por LLM alimentando a geração de imagens) compõem os dois APIs em sequência.

References