API de Image Playground: SwiftUI Sheet, Image Creator programático y control de estilo

Image Playground de Apple Intelligence expone dos rutas de integración para las apps. El modificador SwiftUI imagePlaygroundSheet() presenta la interfaz de generación de imágenes que el sistema muestra al usuario; el desarrollador entrega un concepto inicial (texto o imagen), el usuario itera dentro del sheet y el resultado regresa a la app. El API ImageCreator ejecuta la misma canalización de generación de forma programática: el desarrollador suministra un arreglo de objetos ImagePlaygroundConcept junto con un estilo, y el framework devuelve las imágenes generadas sin mostrar una UI¹. Las dos rutas apuntan a casos de uso distintos. La integración con sheet es la adecuada cuando el usuario debe iterar; la integración programática lo es cuando la app tiene una solicitud de generación específica y muestra el resultado directamente.

El post recorre el API contrastándolo con la documentación de Apple. El marco es “qué ruta de integración coincide con el modelo mental del usuario”, porque elegir la ruta equivocada produce una UX que le quita demasiado control al usuario (programática cuando el usuario quería iterar) o muy poco (sheet cuando el usuario esperaba un resultado de un solo intento).

TL;DR

• imagePlaygroundSheet(isPresented:concept:sourceImage:onCompletion:onCancellation:) es el modificador SwiftUI que presenta el sheet del sistema de Image Playground. El usuario itera; la app recibe la URL de la imagen elegida a través de onCompletion (URL no opcional); la cancelación dispara onCancellation².
• ImageCreator().images(for: [ImagePlaygroundConcept], style: ImagePlaygroundStyle, limit: Int) es la ruta programática (iOS 18.4+). El método devuelve una AsyncSequence de resultados ImageCreator.CreatedImage³.
• ImagePlaygroundConcept lleva la entrada que usa el modelo: descripciones de texto (.text("a watercolor of a cat")), imágenes fuente (.image(...)), dibujos (.drawing(...)) o conceptos extraídos de una referencia (.extracted(from:title:)).
• ImagePlaygroundStyle elige la estética visual. Las apps consultan ImageCreator().availableStyles para descubrir qué casos admite el dispositivo.
• .imagePlaygroundPersonalizationPolicy(_:) acepta .automatic, .enabled o .disabled. .imagePlaygroundGenerationStyle(_:in:) toma un estilo preferido y una lista de estilos permitidos. Úsalos en contextos sensibles a la privacidad o con estética bloqueada.

Las dos rutas: sheet vs. programática

La decisión entre las dos rutas de integración trata sobre quién controla la iteración.

La integración con sheet entrega al usuario la interfaz completa de generación de imágenes del sistema. El usuario escribe prompts, elige variaciones y selecciona la imagen final. El trabajo de la app es lanzar el sheet con un concepto inicial y recibir el resultado elegido. Úsala cuando:

• El usuario tiene una intención creativa que la app no puede predecir por completo.
• La interacción es parte de un flujo creativo (una app de mensajería, una app de notas, un flujo de personalización de perfil).
• El usuario espera iterar antes de comprometerse.

La integración programática le entrega el modelo directamente a la app. La app suministra conceptos y recibe imágenes, sin mostrar la UI del sistema. Úsala cuando:

• La generación es parte de un flujo no interactivo (un avatar generado por el sistema, un activo determinista para una tarjeta de receta, una ilustración de un solo intento).
• La app tiene un requisito estético específico (siempre estilo ilustración, siempre una imagen).
• El usuario no debería ver la iteración; lo que le importa es el resultado.

Las dos rutas comparten el modelo subyacente y respetan la misma configuración de Apple Intelligence a nivel de usuario. La elección es puramente sobre UX.

El sheet de SwiftUI

imagePlaygroundSheet se entrega en varias variantes de sobrecarga sobre View. La forma canónica de 5 parámetros toma un concepto inicial, una referencia opcional a una imagen fuente, más manejadores de finalización y cancelación²:

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

La UX del sheet la controla el sistema. El usuario ve la interfaz estándar de Image Playground de Apple (prompts, selector de estilo, cuadrícula de variaciones, botón “Listo”). El papel de la app es proporcionar el prompt inicial y recibir el resultado. La cancelación dispara el closure dedicado onCancellation en lugar de una URL nula en la finalización; la URL pasada a onCompletion no es opcional.

Para apps que quieren conceptos iniciales más ricos que una sola cadena, las sobrecargas hermanas aceptan [ImagePlaygroundConcept] directamente. Múltiples conceptos se componen: el modelo usa cada uno como una restricción o señal. El orden importa: los conceptos de texto establecen el prompt; los conceptos de imagen establecen una referencia visual; los conceptos de dibujo establecen un contorno.

Variantes de ImagePlaygroundConcept

Apple incluye varios constructores de ImagePlaygroundConcept⁴:

.text(_:). Una descripción de texto corta. El concepto inicial más común.

.image(_:). Una imagen fuente (típicamente una URL o UIImage/NSImage). El modelo la usa como referencia visual de estilo o composición.

.drawing(_:). Un dibujo, típicamente de PencilKit o de una superficie de dibujo personalizada. El modelo interpreta los trazos como una pista estructural.

.extracted(from:title:). Conceptos extraídos de una imagen analizada. La forma de dos argumentos toma una URL fuente (o un tipo de imagen) y un title que describe la extracción. El framework usa análisis en el dispositivo para derivar un concepto adecuado para generación a partir de la referencia.

Los conceptos se componen: pasar [text, image, extracted] al sheet o a ImageCreator permite que el modelo satisfaga múltiples restricciones. El patrón correcto es “lo bastante específico para producir una salida útil, lo bastante laxo para que el modelo tenga margen”: uno o dos conceptos concretos más imágenes de referencia opcionales.

ImageCreator: la ruta programática

ImageCreator es el API programático para apps que quieren generación sin 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)")
}

El método images(for:style:limit:) devuelve una AsyncSequence de resultados ImageCreator.CreatedImage. El modelo de streaming asíncrono permite que las apps muestren resultados parciales (el refinamiento progresivo del modelo) o esperen a la imagen final. El parámetro limit: limita el número de imágenes solicitadas; Apple puede devolver menos según política o estado del dispositivo.

La ruta programática es para iOS 18.4+ y requiere un dispositivo capaz de Apple Intelligence con la función habilitada. El patrón de comprobación de disponibilidad: construye ImageCreator dentro de try, luego lee availableStyles. Una colección availableStyles vacía (o un inicializador que lanza un error) indica que la generación no está disponible en el dispositivo actual; las apps recurren a una ruta no generativa (biblioteca de activos, imagen subida por el usuario, etc.).

Variantes de ImagePlaygroundStyle

El parámetro de estilo restringe la estética visual⁵:

• .animation. El estilo de personajes animados de Apple (formas redondeadas, contornos marcados, rasgos simplificados). Útil para avatares, mascotas, ilustraciones amigables de UI.
• .illustration. Estilo ilustrado plano con estética similar a vector. Útil para infografías, tarjetas de recetas, imágenes conceptuales.
• .sketch. Estilo de boceto a lápiz (añadido en versiones posteriores). Útil para apps de toma de notas, diarios, estéticas dibujadas a mano.

Las apps que quieren una estética consistente entre las imágenes generadas (cada avatar en estilo .animation, cada tarjeta de receta en estilo .illustration) bloquean el estilo en sus llamadas de generación; las apps que quieren exponer la elección muestran un selector de estilo que se asigna a los casos disponibles.

Modificadores de personalización y política

Dos modificadores SwiftUI permiten que las apps restrinjan el comportamiento de Image Playground en su contexto⁶:

.imagePlaygroundPersonalizationPolicy(_:). Toma un valor ImagePlaygroundPersonalizationPolicy: .automatic (predeterminado del sistema), .enabled (permitir explícitamente) o .disabled (prohibir que el sistema haga referencia a contenido personal como contactos/fotos). Usa .disabled para apps en contextos sensibles a la privacidad (médicos, financieros, comunicación anónima).

.imagePlaygroundGenerationStyle(_:in:). Toma un estilo preferido y un arreglo de estilos permitidos. El selector de estilo del usuario (si es visible) se restringe a la lista permitida, y el estilo preferido es el predeterminado. Úsalo cuando la estética de la app requiera restringir o bloquear los estilos disponibles.

Ambos modificadores respetan la configuración de Apple Intelligence a nivel del sistema como un piso. Las apps no pueden anular funciones que el sistema haya deshabilitado; solo pueden restringir más.

Fallas comunes

Tres patrones de los registros de integración de Image Playground:

Llamar a ImageCreator() sin capturar el error del inicializador. En dispositivos que no son de Apple Intelligence, el creator lanza un error en la inicialización. Las apps que no usan try y no capturan el error muestran un error confuso al usuario. Solución: envuelve ImageCreator() en try, inspecciona availableStyles y proporciona una ruta alternativa en caso de fallo (mostrar un placeholder, pedir al usuario que active Apple Intelligence en Configuración o ocultar la función por completo).

Desajustar la ruta de integración con el caso de uso. Un generador de avatares de perfil que usa ImageCreator produce un avatar de un solo intento que el usuario no puede ajustar; un generador de avatares de un solo intento que usa el sheet añade fricción. Haz coincidir la ruta con la expectativa del usuario: si quieren iterar, sheet; si quieren un resultado, programática.

Ignorar el piso de política del sistema. Las apps que intentan eludir la configuración de Apple Intelligence del sistema (p. ej., generar imágenes en un contexto que el usuario ha deshabilitado globalmente) dan con errores de política. Solución: respeta la configuración del sistema; muestra errores significativos cuando Apple Intelligence está deshabilitado en lugar de fallar en silencio.

Lo que este patrón significa para las apps de Apple Intelligence

Tres conclusiones.

1. Elige la ruta de integración según el modelo mental del usuario. Sheet para iteración creativa; programática para generación de un solo intento en flujos no interactivos. El costo de elegir mal es fricción real en la UX.

2. Restringe el estilo y la personalización de manera deliberada. Una app de mensajería que quiere un estilo de avatar consistente pasa un único estilo permitido a .imagePlaygroundGenerationStyle(_:in:). Una app de diario centrada en la privacidad establece .imagePlaygroundPersonalizationPolicy(.disabled). Los valores predeterminados son permisivos (.automatic); las restricciones deliberadas hacen que la función se sienta intencional.

3. Verifica siempre availableStyles de ImageCreator() (o captura el error del inicializador) y ten una alternativa. Apple Intelligence requiere hardware específico (iPhone 15 Pro y posteriores, Macs serie M) más la aceptación del usuario. Las apps que dependen de Image Playground sin comprobaciones de disponibilidad fallan de forma confusa en dispositivos antiguos y en dispositivos donde Apple Intelligence está deshabilitado.

El cluster completo del Ecosistema Apple: App Intents tipados; servidores MCP; la pregunta de enrutamiento; Foundation Models; la distinción entre LLM en runtime vs. tooling; tres superficies; el patrón de fuente única de verdad; dos servidores MCP; hooks para desarrollo en Apple; Live Activities; el contrato de runtime de watchOS; internals de SwiftUI; el modelo mental espacial de RealityKit; la disciplina de esquema en SwiftData; patrones de Liquid Glass; el shipping multiplataforma; la matriz de plataformas; el framework Vision; Symbol Effects; la inferencia con Core ML; el API de Writing Tools; Swift Testing; el Privacy Manifest; la accesibilidad como plataforma; la tipografía de SF Pro; los patrones espaciales de visionOS; el framework Speech; las migraciones de SwiftData; el motor de foco de tvOS; los internals de @Observable; el protocolo Layout de SwiftUI; los SF Symbols personalizados; HDR de AVFoundation; el ciclo de vida de entrenamiento de watchOS; App Intents 2.0 en iOS 26; sobre lo que me niego a escribir. El hub está en la serie del Ecosistema Apple. Para un contexto más amplio sobre iOS con agentes de IA, consulta la guía de desarrollo de agentes en iOS.

FAQ

¿Necesito manejar el caso en que Apple Intelligence no esté disponible?

Sí. Image Playground requiere un dispositivo capaz de Apple Intelligence (iPhone 15 Pro y posteriores, Macs serie M) con la función habilitada. En dispositivos no compatibles, el sheet no se presentará y ImageCreator() lanzará un error en la inicialización. El patrón de comprobación: envuelve ImageCreator() en try e inspecciona availableStyles; una colección vacía o un inicializador que lanza un error indica que la generación no está disponible. Proporciona una alternativa no generativa para los usuarios no compatibles.

¿Puedo personalizar la UI del sheet?

No. El sheet lo controla el sistema. La app suministra el concepto inicial y recibe el resultado; todo lo que hay en medio es la UI de Apple. Si necesitas una UI personalizada, usa el API programático ImageCreator y construye tu propia interfaz de iteración a su alrededor.

¿Qué pasa con las imágenes generadas cuando el usuario descarta el sheet?

La sobrecarga de 5 parámetros de imagePlaygroundSheet proporciona closures onCompletion y onCancellation separados. onCompletion se dispara con una URL no opcional cuando el usuario elige una imagen; onCancellation se dispara cuando el usuario lo descarta sin elegir. Los datos temporales de la imagen los limpia el sistema; las apps que quieran conservar una imagen deben guardarla en su propio almacenamiento dentro del manejador de finalización.

¿Cómo interactúa Image Playground con los permisos de fotos?

El sheet no requiere acceso a la biblioteca de fotos por sí mismo. Si el usuario hace referencia a su biblioteca de fotos dentro del sheet (al buscar una imagen para usar como concepto), el sheet maneja el aviso de permisos internamente. Las apps no necesitan solicitar permiso de fotos de antemano para integrar Image Playground.

¿Puedo generar imágenes en segundo plano?

ImageCreator se ejecuta en primer plano; el framework gestiona los recursos del sistema para la generación. Las apps que quieran generación de imágenes en segundo plano necesitan mantener su app en primer plano (o en un tipo de sesión que permita ejecución continuada, como una sesión de entrenamiento, cubierta en ciclo de vida de entrenamiento de watchOS).

¿Cómo se relaciona esto con el LLM de Foundation Models?

El modelo de Image Playground es independiente del LLM en el dispositivo de Foundation Models (cubierto en Foundation Models LLM en el dispositivo). Los dos comparten la infraestructura del framework de Apple Intelligence pero usan modelos especializados distintos. Las apps que los combinan (prompts generados por LLM que alimentan la generación de imágenes) componen los dos APIs en secuencia.

Referencias