Image Playground API: hoja de SwiftUI, creador de imágenes programático y control de estilo

Actualización (11 de junio de 2026): Apple va a descontinuar ImageCreator, el camino programático que cubre este artículo. Deja de funcionar en iOS 27, iPadOS 27, macOS 27 y visionOS 27. Las APIs basadas en hojas que se cubren en el resto de este artículo siguen siendo el camino con soporte. Lee el artículo completo sobre la deprecación para conocer el calendario y la migración.

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

El artículo recorre la API contra la documentación de Apple. El enfoque es “qué camino de integración coincide con el modelo mental del usuario”, porque elegir el camino equivocado produce una UX que le quita demasiado control al usuario (programático cuando el usuario quería iterar) o demasiado poco (hoja cuando el usuario esperaba un resultado de un solo intento).

TL;DR

• imagePlaygroundSheet(isPresented:concept:sourceImage:onCompletion:onCancellation:) es el modificador de SwiftUI que presenta la hoja de Image Playground del sistema. 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 el camino programático (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 de origen (.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 para contextos sensibles a la privacidad o con estética bloqueada.

Los dos caminos: hoja vs. programático

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

La integración con hoja le entrega al usuario la UI completa de generación de imágenes del sistema. El usuario escribe prompts, elige variaciones y selecciona la imagen final. La tarea de la app es lanzar la hoja 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 forma parte de un flujo de trabajo 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 da a la app el modelo directamente. La app proporciona conceptos y obtiene imágenes de vuelta, sin mostrar la UI del sistema. Úsala cuando:

• La generación forma parte de un flujo no interactivo (un avatar generado por el sistema, un recurso 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 debe ver la iteración; lo que le importa es el resultado.

Los dos caminos comparten el modelo subyacente y respetan la misma configuración de Apple Intelligence a nivel de usuario. La elección tiene que ver puramente con la UX.

La hoja de SwiftUI

imagePlaygroundSheet se entrega en varias variantes sobrecargadas sobre View. La forma canónica de 5 parámetros toma un concepto inicial, una referencia opcional de imagen de origen, además de los 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 de la hoja 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 “Done”). El papel de la app es proporcionar el prompt inicial y recibir el resultado. La cancelación dispara la clausura dedicada onCancellation en lugar de una URL nil en la finalización; la URL que se pasa a onCompletion es no opcional.

Para las apps que quieran 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 una 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 ofrece varios constructores de ImagePlaygroundConcept⁴:

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

.image(_:). Una imagen de origen (típicamente una URL o una UIImage/NSImage). El modelo la usa como referencia visual para el estilo o la 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 de origen (o un tipo de imagen) y un title que describe la extracción. El framework usa análisis en el dispositivo para derivar de la referencia un concepto apto para la generación.

Los conceptos se componen: pasar [text, image, extracted] a la hoja 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 suelto para que el modelo tenga margen”: uno o dos conceptos concretos más imágenes de referencia opcionales.

ImageCreator: el camino programático

[Actualización: Apple descontinuó ImageCreator a partir del 11 de junio de 2026; consulta el artículo sobre la deprecación para conocer el calendario de iOS 27 y cómo migrar. La sección de abajo permanece como documentación histórica de la API.]

ImageCreator es la API programática para las 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 la imagen final. El parámetro limit: limita la cantidad de imágenes solicitadas; Apple puede devolver menos según la política o el estado del dispositivo.

El camino programático es iOS 18.4+ y requiere un dispositivo compatible con Apple Intelligence que tenga la función habilitada. El patrón de verificació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 un camino no generativo (biblioteca de recursos, imagen subida por el usuario, etc.).

Variantes de ImagePlaygroundStyle

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

• .animation. El estilo de personaje animado de Apple (formas redondeadas, contornos marcados, rasgos simplificados). Útil para avatares, mascotas, ilustraciones amigables de UI.
• .illustration. Estilo ilustrado plano con estética tipo vectorial. Útil para infografías, tarjetas de receta, 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 mapea a los casos disponibles.

Modificadores de personalización y de política

Dos modificadores de 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édico, financiero, 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. Usa esto 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 las funciones que el sistema ha deshabilitado; solo pueden restringir aún más.

Fallos comunes

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

Llamar a ImageCreator() sin capturar el error del inicializador. En dispositivos sin Apple Intelligence, el creador lanza un error en la inicialización. Las apps que no usan try y capturan el error muestran un error confuso al usuario. Solución: envuelve ImageCreator() en try, inspecciona availableStyles y proporciona un camino de respaldo en caso de fallo (mostrar un marcador de posición, pedirle al usuario que habilite Apple Intelligence en Configuración u ocultar la función por completo).

No emparejar el camino 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 la hoja añade fricción. Empareja el camino con la expectativa del usuario: si quiere iterar, la hoja; si quiere un resultado, programático.

Ignorar el piso de política del sistema. Las apps que intentan saltarse la configuración de Apple Intelligence del sistema (por ejemplo, generar imágenes en un contexto que el usuario ha deshabilitado globalmente) chocan con errores de política. Solución: respeta la configuración del sistema; muestra errores con sentido cuando Apple Intelligence está deshabilitado en lugar de un fallo silencioso.

Qué significa este patrón para las apps de Apple Intelligence

Tres conclusiones.

1. Elige el camino de integración según el modelo mental del usuario. La hoja para la iteración creativa; programático para la 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 forma 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 enfocada 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 los availableStyles de ImageCreator() (o captura el error del inicializador) y ten un respaldo. Apple Intelligence requiere hardware específico (iPhone 15 Pro y posteriores, Macs con chip de la serie M) más la aceptación del usuario. Las apps que dependen de Image Playground sin verificaciones de disponibilidad fallan de forma confusa en dispositivos más antiguos y en dispositivos donde Apple Intelligence está deshabilitado.

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

FAQ

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

Sí. Image Playground requiere un dispositivo compatible con Apple Intelligence (iPhone 15 Pro y posteriores, Macs con chip de la serie M) con la función habilitada. En dispositivos no compatibles, la hoja no se presentará y ImageCreator() lanzará un error en la inicialización. El patrón de verificació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 un respaldo no generativo para los usuarios no compatibles.

¿Puedo personalizar la UI de la hoja?

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

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

La sobrecarga de 5 parámetros de imagePlaygroundSheet proporciona clausuras onCompletion y onCancellation separadas. onCompletion se dispara con una URL no opcional cuando el usuario elige una imagen; onCancellation se dispara cuando el usuario la descarta sin elegir. El sistema limpia los datos temporales de la imagen; 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?

La hoja no requiere acceso a la biblioteca de fotos por sí sola. Si el usuario hace referencia a su biblioteca de fotos dentro de la hoja (navegando para buscar una imagen que usar como concepto), la hoja maneja la solicitud de permiso internamente. Las apps no necesitan solicitar el permiso de fotos por adelantado para la integración con 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 quieren generación de imágenes en segundo plano necesitan mantener su app en primer plano (o en un tipo de sesión que permita la ejecución continua, como una sesión de entrenamiento cubierta en el ciclo de vida de entrenamientos en 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 on-device LLM). Los dos comparten la infraestructura del framework de Apple Intelligence pero usan modelos especializados distintos. Las apps que los combinan (prompts generados por el LLM que alimentan la generación de imágenes) componen las dos APIs en secuencia.

Referencias