Image Playground API: sheet no SwiftUI, criação programática de imagens e controle de estilo

Atualização (11 de junho de 2026): A Apple está descontinuando o ImageCreator, o caminho programático que este post aborda. Ele para de funcionar no iOS 27, iPadOS 27, macOS 27 e visionOS 27. As APIs baseadas em sheet abordadas no restante deste post continuam sendo o caminho com suporte. Leia o post completo sobre a depreciação para o cronograma e a migração.

O Image Playground do Apple Intelligence expõe dois caminhos de integração para os apps. O modifier imagePlaygroundSheet() do SwiftUI 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. A 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 exibir uma UI¹. Os dois caminhos atendem a casos de uso diferentes. A integração via sheet é a certa quando o usuário deve iterar; a integração programática é a certa quando o app tem uma solicitação de geração específica e exibe o resultado diretamente.

O post percorre a API confrontando-a com a documentação da Apple. O enquadramento é “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ática quando o usuário queria iterar) ou de menos (sheet quando o usuário esperava um resultado de uma única vez).

TL;DR

• imagePlaygroundSheet(isPresented:concept:sourceImage:onCompletion:onCancellation:) é o modifier do SwiftUI que apresenta a sheet do Image Playground do sistema. O usuário itera; o app recebe a URL da imagem escolhida por meio de 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 de texto (.text("a watercolor of a cat")), imagens de origem (.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 esses modifiers 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 tem a ver com quem controla a iteração.

A 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. A tarefa 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 de trabalho criativo (um app de mensagens, um app de notas, um fluxo de personalização de perfil).
• O usuário espera iterar antes de confirmar.

A integração programática dá ao app o modelo diretamente. O app fornece conceitos e recebe imagens de volta, sem exibir 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 uma única vez).
• O app tem um requisito estético específico (sempre o estilo illustration, 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 do Apple Intelligence em nível de usuário. A escolha é puramente sobre UX.

A sheet do SwiftUI

O 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 de origem, mais handlers de conclusão e de 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, grade de variações, botão “Concluído”). O papel do app é fornecer o prompt inicial e receber o resultado. O cancelamento dispara o closure dedicado onCancellation em vez de uma URL nil na conclusão; 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. Múltiplos conceitos se compõem: o modelo usa cada um como uma restrição ou um 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 diversos construtores de ImagePlaygroundConcept⁴:

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

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

.drawing(_:). Um desenho, normalmente 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 origem (ou um tipo de imagem) e um title que descreve a extração. O framework usa análise no dispositivo para derivar da referência um conceito adequado à geração.

Os conceitos se compõem: passar [text, image, extracted] para a sheet ou para o ImageCreator permite que o modelo satisfaça múltiplas restrições. O padrão certo é “específico o suficiente para produzir uma saída útil, solto o suficiente para que o modelo tenha espaço”: um ou dois conceitos concretos mais imagens de referência opcionais.

ImageCreator: o caminho programático

[Atualização: a Apple descontinuou o ImageCreator em 11 de junho de 2026; veja o post sobre a depreciação para o cronograma do iOS 27 e como migrar. A seção abaixo permanece como documentação histórica da API.]

O ImageCreator é a API programática 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 que os apps exibam resultados parciais (o refinamento progressivo do modelo) ou aguardem a imagem final. O parâmetro limit: limita o número de imagens solicitadas; a Apple pode retornar menos com base em políticas ou no estado do dispositivo.

O caminho programático é iOS 18.4+ e exige um dispositivo com capacidade para Apple Intelligence com o recurso ativado. O padrão de verificação de disponibilidade: construa o ImageCreator dentro de um try e depois leia availableStyles. Uma coleção availableStyles vazia (ou um inicializador que lança erro) sinaliza que a geração está indisponí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 e ilustrações amigáveis de UI.
• .illustration. Estilo ilustrado plano com estética semelhante a vetor. Útil para infográficos, cartões de receita e imagens conceituais.
• .sketch. Estilo de esboço a lápis (adicionado em versões posteriores). Útil para apps de anotações, escrita de diário e 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 suas chamadas de geração; apps que querem expor a escolha exibem um seletor de estilo que mapeia para os casos disponíveis.

Modifiers de personalização e de política

Dois modifiers do SwiftUI permitem que os apps restrinjam o comportamento do Image Playground no 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 de permitidos, e o estilo preferido é o padrão. Use isso quando a estética do app exigir restringir ou travar os estilos disponíveis.

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

Falhas comuns

Três padrões dos logs de integração do 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 não capturam o erro exibem um erro confuso ao usuário. Correção: envolva ImageCreator() em um try, inspecione availableStyles e forneça um caminho de fallback em caso de falha (exibir um placeholder, pedir ao usuário para ativar o Apple Intelligence nos Ajustes ou ocultar o recurso por completo).

Descasar o caminho de integração com o caso de uso. Um gerador de avatar de perfil que usa o ImageCreator produz um avatar de uma única vez que o usuário não consegue ajustar; um gerador de avatar de uma única vez 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 contornar as configurações do Apple Intelligence do sistema (por exemplo, gerar imagens em um contexto que o usuário desativou globalmente) batem em erros de política. Correção: respeite a configuração do sistema; exiba erros significativos quando o Apple Intelligence estiver desativado em vez de falhar silenciosamente.

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 de uma única vez 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 um estilo de avatar consistente passa um único estilo permitido para .imagePlaygroundGenerationStyle(_:in:). Um app de diário 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 do ImageCreator() (ou capture o erro do inicializador) e tenha um fallback. O Apple Intelligence exige hardware específico (iPhone 15 Pro e posteriores, Macs com chip da série M) mais a opção ativada pelo 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 o Apple Intelligence está desativado.

O cluster completo do Apple Ecosystem: App Intents tipados; servidores MCP; a questão do roteamento; Foundation Models; a distinção entre LLM de runtime vs de tooling; três superfícies; o padrão de fonte única de verdade; dois servidores MCP; hooks para desenvolvimento Apple; Live Activities; o runtime do watchOS; internals do SwiftUI; o modelo mental espacial do RealityKit; a disciplina de schema do SwiftData; padrões de Liquid Glass; entrega multiplataforma; a matriz de plataformas; Vision framework; Symbol Effects; inferência com Core ML; Writing Tools API; Swift Testing; Privacy Manifest; acessibilidade como plataforma; tipografia do SF Pro; padrões espaciais do visionOS; Speech framework; migrações do SwiftData; focus engine do tvOS; internals do @Observable; protocolo Layout do SwiftUI; SF Symbols personalizados; HDR no AVFoundation; ciclo de vida de treino 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 desenvolvimento de agentes iOS.

FAQ

Preciso tratar o caso de o Apple Intelligence não estar disponível?

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

Posso personalizar a UI da sheet?

Não. A sheet é controlada pelo sistema. O app fornece o conceito inicial e recebe o resultado; tudo entre essas etapas é a UI da Apple. Se você precisa de uma UI personalizada, use a API programática ImageCreator e construa sua própria interface de iteração em torno dela.

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

A sobrecarga de 5 parâmetros do imagePlaygroundSheet fornece closures separados de onCompletion e onCancellation. O onCompletion dispara com uma URL não opcional quando o usuário escolhe uma imagem; o 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 no próprio armazenamento dentro do completion handler.

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

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

Posso gerar imagens em segundo plano?

O ImageCreator é executado 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 contínua, como uma sessão de treino abordada em ciclo de vida de treino no watchOS).

Como isso se relaciona com o LLM dos Foundation Models?

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

Referências