What's New / Apple Intelligence, ML & Evaluation

What's new in ImagePlayground

+9 New~5 Deprecated−1 RemovediOS · macOS · visionOS

ImagePlayground is Apple's framework for generating images using Apple Intelligence. It provides APIs for configuring image creation through types like ImagePlaygroundOptions and ImagePlaygroundStyle.

The 27 SDK adds 9 APIs, including the SizeSpecification struct, the CreationStrategy enum, the ImagePlaygroundOptions.creationStrategy and ImagePlaygroundOptions.sizeSpecification properties, and ImagePlaygroundStyle.any. Five APIs are deprecated, centered on the ImageCreator type, its nested Error type, and images. One API, supportedInterfaceOrientations, is removed.

New

9
extension

ImagePlaygroundOptions.CreationStrategy

NewiOSmacOS
extension ImagePlaygroundOptions.CreationStrategy : Equatable
Declaration
extension ImagePlaygroundOptions.CreationStrategy : Equatable {
}
extension

ImagePlaygroundOptions.CreationStrategy

NewiOSmacOS
extension ImagePlaygroundOptions.CreationStrategy : Hashable
Declaration
extension ImagePlaygroundOptions.CreationStrategy : Hashable {
}
extension

ImagePlaygroundOptions.CreationStrategy

NewiOSmacOS
extension ImagePlaygroundOptions.CreationStrategy : RawRepresentable
Declaration
extension ImagePlaygroundOptions.CreationStrategy : RawRepresentable {
}
var

ImagePlaygroundOptions.creationStrategy

NewiOSmacOS
public var creationStrategy: ImagePlaygroundOptions.CreationStrategy

The options that specify how to interpret the content in the provided input image.

If one of the inputs to the image generation process is an image, this property determines how the system uses that image to generate new images. You can specify an image programmatically, but people can also select images from the system interface. Creation strategies include generating new images that closely resemble the original or using the original only for inspiration.

The default value of this property is automatic.

enum

ImagePlaygroundOptions.CreationStrategy

NewiOSmacOS
public enum CreationStrategy : Int, Codable, Sendable

Options that specify the system strategy for preserving the original image content.

Use these options to specify how much you want the system to preserve the original image you provide.

Declaration
public enum CreationStrategy : Int, Codable, Sendable {

    /// An option to let the system select the creation strategy.
    ///
    /// The system chooses the ``CreationStrategy/generateNew`` option by default.
    case automatic

    /// An option to create an image that more closely resembles the original image,
    /// but also has the modifications you specify.
    ///
    /// This option modifies the image using the prompts you specify, but otherwise
    /// tries to preserve as much of the original image as possible. If the system is
    /// unable to apply the prompts to the image in a suitable way, it falls back to
    /// using the ``CreationStrategy/generateNew`` option.
    case editExisting

    /// An option to create a brand new image, driven primarily by the specified
    /// concepts and loosely inspired by the input image.
    ///
    /// This option provides the most reliable way to generate the image and apply
    /// prompts to it.
    case generateNew

    /// Creates a new instance with the specified raw value.
    ///
    /// If there is no value of the type that corresponds with the specified raw
    /// value, this initializer returns `nil`. For example:
    ///
    ///     enum PaperSize: String {
    ///         case A4, A5, Letter, Legal
    ///     }
    ///
    ///     print(PaperSize(rawValue: "Legal"))
    ///     // Prints "Optional(PaperSize.Legal)"
    ///
    ///     print(PaperSize(rawValue: "Tabloid"))
    ///     // Prints "nil"
    ///
    /// - Parameter rawValue: The raw value to use for the new instance.
    public init?(rawValue: Int)

    /// The raw type that can be used to represent all values of the conforming
    /// type.
    ///
    /// Every distinct value of the conforming type has a corresponding unique
    /// value of the `RawValue` type, but there may be values of the `RawValue`
    /// type that don't have a corresponding value of the conforming type.
    @available(macOS 27.0, iOS 27.0, *)
    @available(tvOS, unavailable)
    @available(watchOS, unavailable)
    public typealias RawValue = Int

    /// The corresponding value of the raw type.
    ///
    /// A new instance initialized with `rawValue` will be equivalent to this
    /// instance. For example:
    ///
    ///     enum PaperSize: String {
    ///         case A4, A5, Letter, Legal
    ///     }
    ///
    ///     let selectedSize = PaperSize.Letter
    ///     print(selectedSize.rawValue)
    ///     // Prints "Letter"
    ///
    ///     print(selectedSize == PaperSize(rawValue: selectedSize.rawValue)!)
    ///     // Prints "true"
    public var rawValue: Int { get }
}
var

ImagePlaygroundOptions.sizeSpecification

NewiOSmacOS
public var sizeSpecification: ImagePlaygroundOptions.SizeSpecification

The requested size for any generated images.

The default value of this property requests the smallest image size with a square aspect ratio.

struct

ImagePlaygroundOptions.SizeSpecification

NewiOSmacOS
public struct SizeSpecification : Hashable, Sendable

A type that specifies image size and aspect ratio information.

The Image Playground framework supports the creation of images with a finite set of sizes and aspect ratios. To request an image of a particular size, call the static closest(to:) method to create an instance of this structure. That method creates a structure with a supported size that most closely matches the size information you provided. The method considers both the resolution and aspect ratio you specified.

Assign an instance of this structure to the sizeSpecification property of your options, and use those options to generate your image.

Declaration
public struct SizeSpecification : Hashable, Sendable {

    /// Creates a new instance of this structure with a size value that best matches
    /// the specified size.
    ///
    /// - Parameters:
    ///     - size: The image size you want.
    /// - Returns: A structure with a supported size that most closely matches the
    /// requested value in `size`.
    ///
    /// This method finds the supported image size that’s closest to the value in the
    /// `size` parameter. The method considers both the resolution and aspect ratio
    /// of the requested size when choosing the output size.
    public static func closest(to size: CGSize) -> ImagePlaygroundOptions.SizeSpecification

    /// Returns a Boolean value indicating whether two values are equal.
    ///
    /// Equality is the inverse of inequality. For any values `a` and `b`,
    /// `a == b` implies that `a != b` is `false`.
    ///
    /// - Parameters:
    ///   - lhs: A value to compare.
    ///   - rhs: Another value to compare.
    public static func == (a: ImagePlaygroundOptions.SizeSpecification, b: ImagePlaygroundOptions.SizeSpecification) -> Bool

    /// Hashes the essential components of this value by feeding them into the
    /// given hasher.
    ///
    /// Implement this method to conform to the `Hashable` protocol. The
    /// components used for hashing must be the same as the components compared
    /// in your type's `==` operator implementation. Call `hasher.combine(_:)`
    /// with each of these components.
    ///
    /// - Important: In your implementation of `hash(into:)`,
    ///   don't call `finalize()` on the `hasher` instance provided,
    ///   or replace it with a different instance.
    ///   Doing so may become a compile-time error in the future.
    ///
    /// - Parameter hasher: The hasher to use when combining the components
    ///   of this instance.
    public func hash(into hasher: inout Hasher)

    /// The hash value.
    ///
    /// Hash values are not guaranteed to be equal across different executions of
    /// your program. Do not save hash values to use during a future execution.
    ///
    /// - Important: `hashValue` is deprecated as a `Hashable` requirement. To
    ///   conform to `Hashable`, implement the `hash(into:)` requirement instead.
    ///   The compiler provides an implementation for `hashValue` for you.
    public var hashValue: Int { get }
}
typealias

ImagePlaygroundOptions.CreationStrategy.RawValue

NewiOSmacOS
public typealias RawValue = Int

The raw type that can be used to represent all values of the conforming type.

Every distinct value of the conforming type has a corresponding unique value of the RawValue type, but there may be values of the RawValue type that don't have a corresponding value of the conforming type.

let

ImagePlaygroundStyle.any

NewiOSmacOS
public static let any: ImagePlaygroundStyle

An option that yields images in a style inferred from the prompt.

Deprecated

5
extension

ImageCreator

DeprecatediOSmacOSvisionOS
extension ImageCreator
DeprecatedUse ImagePlaygroundViewController or imagePlaygroundSheet.
Declaration
extension ImageCreator {

    /// Errors that can occur during the image generation process.
    public enum Error {

        /// An error that indicates the device doesn’t support image generation.
        ///
        /// Make sure the device has the hardware required to run models.
        case notSupported

        /// An error that indicates image creation is currently unavailable.
        ///
        /// This error can occur if the device doesn’t yet have the models it
        /// needs to complete the request.
        case unavailable

        /// An error that occurs in response to cancellation of the parent task.
        case creationCancelled

        /// An error that indicates the system cannot use one of the source
        /// images because the face in it is too small.
        case faceInImageTooSmall

        /// An error that indicates the input text uses an unsupported language.
        case unsupportedLanguage

        /// An error that indicates the system cannot use one of the specified
        /// source images.
        case unsupportedInputImage

        /// An error that indicates the app is hidden or in the background.
        ///
        /// Apps must perform image creation only when running in the foreground.
        case backgroundCreationForbidden

        /// An error that indicates a general failure occurred during image creation. 
        case creationFailed

        /// An error that indicates that a source image containing a person's face
        /// needs to be added in order to complete the request.
        @available(iOS 26.0, macOS 26.0, *)
        @available(watchOS, unavailable)
        @available(tvOS, unavailable)
        case conceptsRequirePersonIdentity

        /// Returns a Boolean value indicating whether two values are equal.
        ///
        /// Equality is the inverse of inequality. For any values `a` and `b`,
        /// `a == b` implies that `a != b` is `false`.
        ///
        /// - Parameters:
        ///   - lhs: A value to compare.
        ///   - rhs: Another value to compare.
        public static func == (a: ImageCreator.Error, b: ImageCreator.Error) -> Bool

        /// Hashes the essential components of this value by feeding them into the
        /// given hasher.
        ///
        /// Implement this method to conform to the `Hashable` protocol. The
        /// components used for hashing must be the same as the components compared
        /// in your type's `==` operator implementation. Call `hasher.combine(_:)`
        /// with each of these components.
        ///
        /// - Important: In your implementation of `hash(into:)`,
        ///   don't call `finalize()` on the `hasher` instance provided,
        ///   or replace it with a different instance.
        ///   Doing so may become a compile-time error in the future.
        ///
        /// - Parameter hasher: The hasher to use when combining the components
        ///   of this instance.
        public func hash(into hasher: inout Hasher)

        /// The hash value.
        ///
        /// Hash values are not guaranteed to be equal across different executions of
        /// your program. Do not save hash values to use during a future execution.
        ///
        /// - Important: `hashValue` is deprecated as a `Hashable` requirement. To
        ///   conform to `Hashable`, implement the `hash(into:)` requirement instead.
        ///   The compiler provides an implementation for `hashValue` for you.

Truncated.

extension

ImageCreator.Error

DeprecatediOSmacOSvisionOS
extension ImageCreator.Error : Equatable
DeprecatedUse ImagePlaygroundViewController or imagePlaygroundSheet.
Declaration
extension ImageCreator.Error : Equatable {
}
extension

ImageCreator.Error

DeprecatediOSmacOSvisionOS
extension ImageCreator.Error : Hashable
DeprecatedUse ImagePlaygroundViewController or imagePlaygroundSheet.
Declaration
extension ImageCreator.Error : Hashable {
}
func

images

DeprecatediOSmacOSvisionOS
final public func images(for concepts: [ImagePlaygroundConcept], style: ImagePlaygroundStyle, options: ImagePlaygroundOptions, limit: Int) -> some AsyncSequence<ImageCreator.CreatedImage, any Error>
DeprecatedUse ImagePlaygroundViewController or imagePlaygroundSheet.

Creates one or more images from the provided description and style information and returns the results asynchronously.

It is a programmer error to specify a style that’s not in the availableStyles property.

  • concepts: An array of initial concepts (text descriptions, concepts extracted

from text, drawings) that describe the expected contents of the returned images.

  • options: Options that influence the image creation behavior.
  • limit: The maximum number of images you want the system to create.

The system limits the maximum number of images to 4.

Call this method to start the image generation process with the specified parameters. The method runs asynchronously and returns the results using the provided <doc://com.apple.documentation/documentation/swift/asyncsequence> object. The following example configures an image creator, starts the creation of the images, and processes the generated images as they arrive:

do {
    let creator = try await ImageCreator()
    guard let style = creator.availableStyles.first else { return }
    var options = ImagePlaygroundOptions()
    options.creationVariety = .high
    options.personalization = .enabled
    options.sizeSpecification = ImagePlaygroundOptions.SizeSpecification.closest(to: CGSize(width: 1024.0, height: 1024.0))

    let images = creator.images(
        for: [.text("A cat wearing mittens.")]
        style: style,
        options: options,
        limit: 4)

    // Receive the images.
    for try await image in images {
        let anImage = image.cgImage

        // Do something with the image.
    }
}
catch ImageCreator.Error.notSupported {
    print(“Image creation not supported on the current device.”)
}

Parameters

style
The style you want the model to apply to the output image.

ReturnsAn asynchronous stream you use to receive the images.

typealias

ImageCreator.Error.AllCases

DeprecatediOSmacOSvisionOS
public typealias AllCases = [ImageCreator.Error]
DeprecatedUse ImagePlaygroundViewController or imagePlaygroundSheet.

A type that can represent a collection of all values of this type.

Removed

1
var

supportedInterfaceOrientations

RemovediOS
override dynamic public var supportedInterfaceOrientations: UIInterfaceOrientationMask { get }
RemovedAbsent from the 27 SDK interface. Declaration shown is from the 26 SDK.

No APIs match your filter.

← More in Apple Intelligence, ML & Evaluation