Set image quality via the Imagine API

Pin generation quality on Imagine Image 2.0 when drafts should stay cheap on low, when edits or finals need medium, or when you want the service default auto made explicit in the request body. Official Image Generation documents the optional quality parameter with allowed values low, medium, and auto, supported only for grok-imagine-image-2.0. When omitted, the default is auto, which currently uses low for image generation and medium for image editing. Images bill at the quality they are served at per Pricing. Pair this with a baseline still from Generate a still with the Imagine Image 2.0 API; consumer Quality Mode on grok.com stays in Open Imagine Quality Mode and is a different surface from this API field.

What you need

An xAI API key with Imagine image access, model id grok-imagine-image-2.0, and a prompt (plus edit inputs when you call the edit path) are the minimum inputs for a quality-pinned request. Neighboring API controls include Set resolution on Imagine API images, Set aspect ratio on Imagine API images, and Edit an image with the Imagine API. More API jobs live on the API hub.

Pin quality on a generation request

1. Export the API key outside of source control before any generation call that pins quality for cost attribution:

export XAI_API_KEY="your_api_key"

2. Generate with an explicit quality value in the JSON body, using low when you want draft throughput over peak fidelity:

curl -X POST https://api.x.ai/v1/images/generations   -H "Content-Type: application/json"   -H "Authorization: Bearer ${XAI_API_KEY}"   -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "A watercolor painting of a lighthouse at dawn",
    "quality": "low"
  }'

3. With the xAI Python SDK, pass the same field on sample so quality stays aligned with the REST body:

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
response = client.image.sample(
    prompt="A watercolor painting of a lighthouse at dawn",
    model="grok-imagine-image-2.0",
    quality="low",
)
print(response.url)

4. For OpenAI-compatible clients, send quality in the JSON body (or extra_body when the SDK only forwards known OpenAI image fields), then download temporary URLs promptly because response URLs expire.

5. Switch to "quality": "medium" for finals you intend to keep, or "auto" when you want the documented service default written into the request for auditability, and combine with resolution (1k / 2k) and aspect_ratio when those jobs already set framing independently of quality.

When auto is enough

Leaving quality omitted still follows auto for Image 2.0, which is acceptable for exploratory prompts where cost dashboards do not need a pinned tier. Pinning matters when draft traffic must attribute to low, when edit pipelines should not silently fall back to a different default than generation, or when a runbook forbids relying on undocumented default drift across releases.

Pitfalls

Sending quality on older Imagine image model ids that do not document the field fails or is ignored, so stick to grok-imagine-image-2.0 for this control. Assuming consumer Quality Mode on grok.com/imagine sets this API parameter leaves server-side requests on auto/low while the website UI looks upgraded. Forgetting that billing follows served quality undercounts spend when drafts stay on medium by habit instead of an intentional pin.