Check respect_moderation on Imagine image

Read the moderation flag on a finished Imagine image response before you download, embed, or publish the still, because a filtered result can look successful until you notice the usable URL or bytes are missing. Official Image Generation Response Details document respect_moderation on the xAI SDK image response: the field is true when the image respects moderation rules, and when it is false you should treat the asset as filtered instead of saving response.url. Create a key and load credits at console.x.ai, then branch on this flag on every path that consumes an Imagine image result.

What you need

An XAI_API_KEY with Imagine image access, a completed client.image.sample (or REST /v1/images/generations) response, and application logic that refuses to treat a filtered result as a publishable file. Use the same check for single generations, sample_batch / n variations, edits that return the same metadata shape, and any helper that wraps the SDK. Neighboring jobs include Check respect_moderation on Imagine video for the video twin, Generate a still with the Imagine API for the baseline call, and Set image quality via the Imagine API when quality knobs change how you bill the attempt. Browse more API jobs on the API hub when you are wiring related tool calls.

Branch on the flag after generate

1. Export the key locally and keep it out of chat logs and public repos before any sample call:

export XAI_API_KEY="your_api_key"

2. Prefer the SDK pattern from the docs when sample() returns a response object with metadata, and only print or download the URL when moderation passed:

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client.image.sample(
    prompt="A collage of London landmarks in a stenciled street-art style",
    model="grok-imagine-image-2.0",
)

if response.respect_moderation:
    print(response.url)
    print(f"Model: {response.model}")
else:
    print("Image filtered by moderation")

3. When you generate several variations in one request, inspect the flag on each item before you enqueue downloads, because one filtered sample in a batch must not be treated as a blank CDN glitch:

responses = client.image.sample_batch(
    prompt="A futuristic city skyline at night",
    model="grok-imagine-image-2.0",
    n=4,
)

for i, image in enumerate(responses):
    if image.respect_moderation:
        print(f"Variation {i + 1}: {image.url}")
    else:
        print(f"Variation {i + 1}: filtered by moderation")

4. On REST or OpenAI-compatible clients, map the same policy onto whatever moderation or empty-url fields your response JSON exposes for the image object, and fail closed whenever the usable asset URL or base64 payload is empty after a completed status.

How to treat a filtered result

Do not retry the identical prompt in a tight loop hoping the flag flips; change the prompt or drop the request from the publish pipeline and log respect_moderation=false with the model id for support. Temporary image URLs from successful generations still expire, so download promptly after a true check rather than storing only the URL in a long-lived queue. The SDK also exposes response.model so you can record which concrete model served the still after alias resolution.

Pitfalls

Skipping the flag and saving response.url blindly can ship an empty or unusable asset into your CDN when moderation filtered the output. Concurrent AsyncClient gathers and sample_batch both need per-image checks, because sibling prompts in the same wave can pass and fail independently. Video jobs use the same field name on a different endpoint — reuse the branching habit from Check respect_moderation on Imagine video, but keep image and video poll or download paths separate so you do not read a video URL off an image response.