VAE: Visual decoder for image generation

Introduction

The vae parameter specifies which Variational Autoencoder to use for converting the model's internal representations into the final image.

Generation happens in latent space, and the VAE decoder is the last step of it: the network that turns the finished latent into visible pixels. Because it is a separate network, it can be replaced with another one, which can improve color accuracy, reduce artifacts, or better handle specific content types.

Swapping the decoder is a diffusion-architecture feature. Most of the catalog ships a fixed decoder as part of the pipeline and does not expose this choice.

Default SDXL VAELuna XL VAE

Request structure

The vae parameter is a string model identifier passed at the top level of your generation request.

import { createClient } from '@runware/sdk'

const client = await createClient({ apiKey: process.env.RUNWARE_API_KEY })
await client.connect()

const [result] = await client.run({
  model: '<model-air>',
  positivePrompt: 'Smiling anime girl with pink twin tails and violet eyes',
  vae: '<vae-model-air>',
  steps: 30,
  width: 1024,
  height: 1024
})

import asyncio
import os

from runware import Runware


async def main():
    async with Runware(api_key=os.environ["RUNWARE_API_KEY"]) as client:
        results = await client.run({
            "model": "<model-air>",
            "positivePrompt": "Smiling anime girl with pink twin tails and violet eyes",
            "vae": "<vae-model-air>",
            "steps": 30,
            "width": 1024,
            "height": 1024
        })


asyncio.run(main())

curl https://api.runware.ai/v1 \
  -H "Authorization: Bearer $RUNWARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "taskType": "imageInference",
      "model": "<model-air>",
      "positivePrompt": "Smiling anime girl with pink twin tails and violet eyes",
      "vae": "<vae-model-air>",
      "steps": 30,
      "width": 1024,
      "height": 1024
    }
  ]'

runware run "<model-air>" \
  positivePrompt="Smiling anime girl with pink twin tails and violet eyes" \
  vae="<vae-model-air>" \
  steps=30 \
  width=1024 \
  height=1024

{
  "taskType": "imageInference",
  "model": "<model-air>",
  "positivePrompt": "Smiling anime girl with pink twin tails and violet eyes",
  "vae": "<vae-model-air>",
  "steps": 30,
  "width": 1024,
  "height": 1024
}

What custom VAEs affect

Custom VAEs can change several aspects of the final image:

• Color reproduction: Different VAEs produce different color profiles. Some boost saturation, others improve color accuracy. The default SDXL VAE, for example, is known to occasionally produce washed-out or slightly desaturated colors, which is why community VAEs exist to correct this.
• Detail preservation: Some VAEs better preserve fine details in the latent-to-pixel conversion, resulting in sharper textures and clearer edges.
• Artifact reduction: Specialized VAEs can reduce common issues like color banding in gradients, blotchy skin tones, or NaN color artifacts (black spots) that the default VAE sometimes produces.

When to change the VAE

For most workflows, the default VAE is fine. Consider changing it when:

• You notice washed-out colors or desaturation in your output, especially with SDXL models.
• You see black spots or NaN artifacts, which indicate the default VAE's fp16 precision issue.
• You're generating anime or stylized content and want bolder colors or cleaner flat fills.
• You're getting color banding in smooth gradients (skies, skin, backgrounds).

If you're not experiencing any of these issues, there's no need to override the default.

Tips

1. Try a VAE before blaming the model. If your SDXL output looks washed out or has black spots, swapping the VAE is often faster and cheaper than switching models.
2. Match the VAE to the architecture. SD 1.5 VAEs won't work with SDXL models and vice versa. Always check compatibility before applying.
3. Don't stack VAE changes with other fixes. If you're troubleshooting color issues, change the VAE in isolation first. Adjusting the VAE, prompt, and CFG simultaneously makes it impossible to identify what fixed the problem.