Skip to main content
Unlayer Docs
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

Picking an Image Model

features.ai.image.model controls the preferred model for AI image generation and editing — the AI Assistant chat and the Image Editor’s AI chat. It is independent of features.ai.model, which only affects the assistant's text/chat model.

Recommended: let Unlayer pick

Leave features.ai.image.model unset and Unlayer picks the best image model for you. Set it only when you need to pin a specific provider or model.

Set features.ai.image.enabled to false to disable image workflows in the AI Assistant chat. This leaves the standalone Image Editor unchanged. An explicit image.enabled takes precedence over the deprecated features.ai.magicImage flag.

Pin a model​

features.ai.image.model mirrors features.ai.model. It accepts:

  • a "<provider>/<modelId>" pair (e.g. "openai/gpt-image-2", "google/gemini-3.1-flash-image") — pins both provider and model, unambiguous;
  • a bare model id (e.g. "gpt-image-2");
  • a provider name (e.g. "openai", "google") — starts on that vendor and lets Unlayer pick that provider's default image model.

The selected model is the first choice. If that provider is overloaded, rate-limited, unavailable, or returns another transient provider error, Unlayer may retry the request against a fallback image model when you set fallbackModels to true or an explicit ordered list.

unlayer.init({
  features: {
    ai: {
      enabled: true,
      assistant: true,

      image: {
        // Provider only — Unlayer picks that provider's image model:
        model: 'openai',

        // Or pin an exact model:
        // model: 'openai/gpt-image-2',
        // model: 'google/gemini-3.1-flash-image',

        // Optional quality tier (low | medium | high).
        // quality: 'high',

        // Optional transient-outage fallback controls:
        // fallbackModels: ['google/gemini-3.1-flash-image', 'openai/gpt-image-1.5'],
        // fallbackModels: true,
        // fallbackModels: false,
      },
    },
  },
});

Supported providers: google and openai. An unsupported provider or image model is rejected.

Gemini model IDs that Google has shut down (gemini-2.5-flash-image and gemini-3.1-flash-image-preview) are still accepted and run on gemini-3.1-flash-image, so existing configurations keep working.

Configure fallback image models​

features.ai.image.fallbackModels controls the transient-outage fallback tail for image generation and editing in the builder Assistant and the Assistant API:

  • omit it to use Unlayer's default fallback picks only when features.ai.image.model is unset;
  • set true to use Unlayer's default fallback picks even when features.ai.image.model pins a provider or model;
  • set false to disable the default outage fallback tail;
  • pass an ordered model array to replace the default fallback picks.

Retries are used for provider availability failures such as network errors, overloads, rate limits, and 5xx responses. They are not used for invalid image prompts, unsupported model IDs, invalid API keys, authorization errors, credit exhaustion, or errors that require a change from you or Unlayer.

When an Assistant edit must preserve transparency, or the user requests a transparent image, Unlayer first selects an alpha-capable model from this configured chain. Currently that requires openai/gpt-image-1.5 or openai/gpt-image-2 (provider preview support). No provider outside the chain is added. Pinning an incompatible model without a compatible fallback stops the edit before generation; an opaque output is rejected without charging image credits. Pure grayscale conversions use a pixel conversion instead of generation, preserving dimensions and transparency. Conversation and image-description usage still apply.

The standalone Image Editor currently forwards model and quality, but not fallbackModels. With no pinned model, it uses the server's default fallback chain; a pinned model does not opt into that chain.

Quality vs. cost​

quality is optional. OpenAI defaults to medium when omitted. Gemini leaves output resolution at the provider's default when omitted; explicit low, medium, and high map to 1K, 2K, and 4K output-resolution requests. Supported resolution and the resulting credit cost depend on the selected model.

Supported model IDs are gpt-image-1.5, gpt-image-2, and gemini-3.1-flash-image. Generation and editing use the same selection rules. Image input, output, and text usage are priced separately; see Pricing.

The direct Images API accepts model, quality, and fallbackModels at the request root. Conversational image requests use features.ai.image; their top-level model still selects the conversation model.